4 Desktop
py-rocket-base includes the xfce4 Desktop UI where you can run applications. It is built off freedesktop (which is helpful to know if you are debugging and configuring). A common application is to run QGIS or java-based applications. py-rocket-base looks for files with the ending .desktop
, .xml
(optional), and .png
or .svg
(optional) associated with an application in a directory called Desktop in your repo.
py-rocket-base puts these .desktop
files in /usr/share/Desktop
. Typically these desktop files are in ~/Desktop
. But in a JupyterHub, the home directory is often persistent and py-rocket-base tries not to alter the user home directory. Also there might be orphaned desktop files in ~/Desktop
and so the user desktop UI would be inconsistent between users. Using /usr/share/Desktop
does mean that users cannot add their own persistent applications to xfce4 Desktop but this would be difficult anyhow without root access in many cases.
py-rocket-base has Java (openjdk-11-jdk
and openjdk-11-jre
) pre-installed as part of the rocker R/RStudio installation. So Java applications do work as long as they work with this version of Java.
openjdk version "11.0.24" 2024-07-16
OpenJDK Runtime Environment (build 11.0.24+8-post-Ubuntu-1ubuntu322.04)
OpenJDK 64-Bit Server VM (build 11.0.24+8-post-Ubuntu-1ubuntu322.04, mixed mode, sharing)
4.1 Adding an application in your child docker image
Use the pyrocket script install-desktop.sh
to set up the desktop and move your files to the proper location. Provide a path to a directory with your Desktop files as the argument to the script. Here is the code for your Docker file. This script must be run as root.
USER root
COPY ./Desktop /tmp/Desktop
RUN /pyrocket_scripts/install-desktop.sh /tmp/Desktop
RUN rm -rf /tmp/Desktop
USER ${NB_USER}
4.1.1 Create the Desktop directory
Create a directory for the Desktop file and add the .desktop and optional .png and .xml files. The pyrocket script install_desktop.sh
will move them to the correct places (/usr/share/applications
and /usr/share/Desktop
, /usr/share/mime/packages
and icon locations).
your-repo/
├── Dockerfile
├── optional extra files
├── Desktop/
│ ├── qgis.desktop
│ ├── qgis.xml
│ └── qgis.png
4.1.1.1 .desktop file
The .desktop
file is a configuration file that describes how an application is launched. The required parts are Name, Exec and Type. MimeType specifies what types of files the application can use (optional). If you included an icon in your Desktop directory, then that will be registered and you can use the filename without a path. However, sometimes the icon is installed with the application and in that case you need the full path. See the icon section below.
cdat.desktop
[Desktop Entry]
Type=Application
Name=CWUtils
GenericName=CoastWatch Data Analysis Tool
Icon=cdat
TryExec=cdat
Exec=cdat %F
Terminal=false
StartupNotify=false
Categories=Qt;Education;Science;Geography;
Keywords=map;globe;
4.1.1.2 .xml
You can specify the mime types via xml.
4.1.1.3 icons
You can include a png or svg for the icon. py-rocket-base will place this in /usr/share/icons/hicolor
. If you put your icon file in the Desktop directory in your repo, then in your desktop file, use the file name without the extension. If for some reason, your icon is not showing up, use the direct url /srv/repo/Desktop/your-icon-name.png
. If the icon cache does not update properly, you have the use the full url.
Icon=cdat
You can also use an absolute file path.
If an icon is installed with your application, it will be in the installation files.
Icon=/srv/conda/envs/notebook/share/qgis/images/icons/qgis-icon-512x512.png
or if you include an icon in your Desktop
directory, it will be in /srv/repo/Desktop
(but in that case it is also registered as an icon so you can just use cdat
).
Icon=/srv/repo/Desktop/cdat.png
4.1.2 Install the application
How you install the application really varies. Here are 2 examples.
QGIS
- add
qgis
toenvironment.yml
- add
libgl1-mesa-glx
toapt.txt
- add the
qgis.desktop
file to your Desktop directory
qgis.desktop
# From: https://github.com/qgis/QGIS/blob/ltr-3_28/linux/org.qgis.qgis.desktop.in
[Desktop Entry]
Type=Application
Name=QGIS Desktop
GenericName=Geographic Information System
Icon=/srv/conda/envs/notebook/share/qgis/images/icons/qgis-icon-512x512.png
TryExec=qgis
Exec=qgis %F
Terminal=false
StartupNotify=false
Categories=Qt;Education;Science;Geography;
MimeType=application/x-qgis-project;application/x-qgis-project-container;application/x-qgis-layer-settings;application/x-qgis-layer-definition;application/x-qgis-composer-template;image/tiff;image/jpeg;image/jp2;application/x-raster-aig;application/x-raster-ecw;application/x-raster-mrsid;application/x-mapinfo-mif;application/x-esri-shape;application/vnd.google-earth.kml+xml;application/vnd.google-earth.kmz;application/geopackage+sqlite3;
Keywords=map;globe;postgis;wms;wfs;ogc;osgeo;
StartupWMClass=QGIS3
CoastWatch Utilities
Add this to the docker file to install
USER root
# Install cwutils
RUN cd /tmp && \
wget https://www.star.nesdis.noaa.gov/socd/coastwatch/cwf/cwutils-4_0_0_198-linux-x86_64.tar.gz && \
tar -zxf cwutils-4_0_0_198-linux-x86_64.tar.gz && \
rm -rf cwutils-4_0_0_198-linux-x86_64.tar.gz
ENV PATH=${PATH}:/tmp/cwutils_4.0.0.198/bin
ENV MANPATH=${MANPATH}:/tmp/cwutils_4.0.0.198/doc/man
ENV INSTALL4J ADD VM PARAMS=-Dsun.java2d.uiScale=2.0
USER ${NB_USER}
Add this cdat.desktop
file to Desktop directory
[Desktop Entry]
Type=Application
Name=CWUtils
GenericName=CoastWatch Data Analysis Tool
Icon=/srv/repo/Desktop/cdat.png
TryExec=cdat
Exec=cdat %F
Terminal=false
StartupNotify=false
Categories=Qt;Education;Science;Geography;
Keywords=map;globe;
Add cdat.png
icon to Desktop directory. How do you know that the command to open the application is cdat
? You read the application installation documentation and it will tell you how to open the application from a terminal (command line).
4.2 What’s happening
To add new desktop applications, one needs to do the following. py-rocket-base does these steps automatically (via the start script) so that the user only has to put files into a Desktop directory in the docker build repo.
- Install the application. See examples.
- Add a
.desktop
file to an application directory. py-rocket-base puts these in/usr/share/applications
but you will also see${HOME}/.local/share/applications/
. - To have an icon on the Desktop, you create a folder Desktop and tell XDG what directory to use. The directory is specified in
~/.config/user-dirs.dirs
which XDG sets. By default (XDG), this folder is~/Desktop
but you can set it to something else. py-rocket-base sets a default value in/etc/xdg/user-dirs.defaults
. This updates~/.config/user-dirs.dirs
when the/etc/xdg/xfce4/xinitrc
start script is run (when the/desktop
button is clicked). - XDG looks for .desktop files in the Desktop directory. py-rocket-base creates a soft link to the
.desktop
files in/usr/share/applications/
in/usr/share/Desktop
.
See this Medium article for a description.