# Graphical desktop environment on the UK Biobank RAP (Research Analysis Platform)

This document contains details on installing a graphical Linux desktop environment on the UK Biobank Research Analysis Platform (RAP).

These instructions use a pre-prepared Docker image which contains Ubuntu and the XFCE desktop environment, and has noVNC installed for remote access to the desktop. Docker images are available which have a Linux desktop environment and noVNC set up - you can download and use these Docker images on the RAP via the _ttyd_ application.

> For advanced users, it is possible to install noVNC directly into a RAP session via the _ttyd_ or _Cloud Workstation_ applications, but accomplishing that is beyond the scope of this document. Feel free to inspect/re-use the commands in the [`pauldmccarthy/rap-novnc-docker-images` `Dockerfile` definitions](https://github.com/pauldmccarthy/rap-novnc-docker-images) if you wish to build your own solution.

## Instructions

1. Log into the RAP portal at https://ukbiobank.dnanexus.com/login

2. Click on _Tools_ at the top, and select _Tools Library_.

3. Find and click on the _ttyd_ app (it may not be on the first page).

4. Click the _Run_ button at the top.

5. Set _Output to_ to a location within the RAP project workspace you wish to work within, and click _Next_.

6. Click the _Start Analysis_ button at the top-right.

7. Click _Edit Instance Type_ to select your RAM/CPU resources.

8. Click the _Launch Analysis_ button.

9. You will be taken to the _Monitor_ page - click on the new entry corresponding to your new _ttyd_ session.

10. You will need to wait several minutes for the session to start up. When it is ready, click the _Open Worker URL_ link. This wil open a new web browser tab with a UNIX shell.

11. Run these commands in the shell (change `pauldmccarthy/ubuntu-novnc` to the Docker image you wish to run - more on this below):

    env | egrep "^DX_" > dx.env
    docker run --detach --name novnc \
      --network host                 \
      --env-file dx.env              \
      -v /mnt/project:/mnt/project   \
      pauldmccarthy/ubuntu-novnc
    docker logs -f novnc

12. Once the image has started running, a message starting with _Navigate to this URL_ will be printed. Copy+paste the URL into a new web browser window to open your desktop session.

The [`pauldmccarthy/ubuntu-novnc`](https://hub.docker.com/r/pauldmccarthy/ubuntu-novnc) Docker image is a minimal Ubuntu system with the XFCE desktop environment installed, but without much else. Once you have started running the container, you can install whatever software you want using `apt` or `micromamba`. The `dx` command is also available, gibving you access to your RAP project workspace.

## Use a different Docker image, or build your own

Some other Docker images are available - for example:

- The [`pauldmccarthy/fsl-novnc`](https://hub.docker.com/r/pauldmccarthy/fsl-novnc) image comes with [FSL](https://fsl.fmrib.ox.ac.uk/fsl/docs/) installed, for MRI image analysis.
- The [`pauldmccarthy/fsleyes-novnc`](https://hub.docker.com/r/pauldmccarthy/fsleyes-novnc) image just contains [FSLeyes](https://fsl.fmrib.ox.ac.uk/fsl/docs/utilities/fsleyes.html) and a few low-level FSL utilities, for MRI image visualisation and basic analysis.
- The [`pauldmccarthy/workbench-novnc`](https://hub.docker.com/r/pauldmccarthy/workbench-novnc) image contains [Connectome Workbench](https://humanconnectome.org/software/connectome-workbench), including the `wb_view` and `wb_command` utilites for NIfTI/CIfTI visualisation and processing.

You can also build your own Docker image with whatever software you need - simply use `pauldmccarthy/ubuntu-novnc` as the base image, or copy the contents of its `Dockerfile` into your own. Refer to the [GitHub repository](https://github.com/pauldmccarthy/rap-novnc-docker-images) for more details.

## Access your UK Biobank data

When running on the RAP, we recommend running the Docker image with the following commands:

env | egrep "^DX_" > dx.env
docker run --name novnc --detach \
  --network host                 \
  --env-file dx.env              \
  -v /mnt/project:/mnt/project   \
  pauldmccarthy/ubuntu-novnc
docker logs -f novnc

The `pauldmccarthy/*-novnc` Docker images have the `dx` command installed, however in order for it to be associated with your RAP account, you need to pass the relevant environment variables from the _ttyd_ session into the running Docker container. You can do this by saving them to a file, and then passing that file to `docker run` via its `--env-file` option. You may also need to re-select your RAP project by running:

dx select

Once this has been done, you can use `dx` to upload/download data to/from your RAP workspace:

- `dx ls` - list the contents of your project workspace.
- `dx download <file>` - download a file from your project workspace to the workstation.
- `dx upload <file>` - upload a file from the workstation to your project workspace.

Within the _ttyd_ session, your RAP project workspace is also mounted (read-only) at `/mnt/project/` - in the above `docker run` command, this is mounted into the Docker container via the `-v` option. This means you can access your Project files without having to run `dx download`.

The Docker container must be started in "detached" mode (via the `--detach` option) - this ensures that your desktop session is not killed in the event that you close the _ttyd_ browser window (or e.g. close your laptop lid).