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 && \
  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 to environment.yml
  • add libgl1-mesa-glx to apt.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.