This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Neurodesktop

The plug-and-play, browser-accessible, containerised data analysis environment.

1 - Getting Started

Select your operating system to get started with neurodesktop.

1.1 - Linux

Install neurodesktop on Linux

Minimum System Requirements

  1. At least 3GB free space for neurodesktop base image
  2. Docker requirements. Details found under https://docs.docker.com/get-docker/

Quickstart

1. Install Docker/Podman

Install Docker from here: https://docs.docker.com/get-docker/. Additional information available below. Neurodesk also works with Podman.

2. Run Neurodesktop

Before the first run, create a local folder where the downloaded applications will be stored, e.g. ~/neurodesktop-storage

Then use one of the following options to run Neurodesktop:

Option 1: NeuroDesktop.run

Download and run the following executable https://github.com/NeuroDesk/neurodesktop/raw/main/Linux_run_Neurodesk/NeuroDesktop.run

Option 2: Using Terminal

  1. Open a terminal, and type the folowing command to automatically download the neurodesktop container and run it
sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813
  1. Once neurodesktop is downloaded i.e. guacd[77]: INFO: Listening on host 127.0.0.1, port 4822 is displayed in terminal, leave the terminal open and neurodesktop running (i.e., do not press CTRL+C)

  2. Open a browser and go to:

http://localhost:8080/#/?username=user&password=password
  1. Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”

  2. If it is the first time you use Neruodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.

  3. Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.

  4. For an optimal experience, switch your browser to full-screen mode by following the instructions for your browser here: https://www.thewindowsclub.com/open-chrome-edge-or-firefox-browser-in-full-screen-mode

Deleting neurodesktop:

When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")

  1. Click on the terminal from which you ran neurodesktop

  2. Press Ctrl-C

  3. Run:

docker stop neurodesktop
  1. Run:
docker rm neurodesktop

Installing Docker

For general installation instructions, refer to https://docs.docker.com/get-docker/

RHEL/CentOS (yum-based)

Refer to https://docs.docker.com/engine/install/centos/

One example to install docker in a yum-based distribution could look like this:

sudo dnf install -y yum-utils 
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io
# or if dnf not found: sudo yum install docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker
sudo systemctl start docker
sudo docker version
sudo docker info
sudo groupadd docker
sudo usermod -aG docker $USER
sudo chown root:docker /var/run/docker.sock
newgrp docker

Ubuntu/Debian (apt-based)

Refer to https://docs.docker.com/engine/install/ubuntu/

One example to install docker in a apt-based distribution could look like this:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

GPU support

RHEL/CentOS (yum-based)

sudo yum install nvidia-container-toolkit -y

Running neurodesktop container with GPU

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)" \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DISABLE_REQUIRE=1 \
  -p 8080:8080 -h neurodesktop-20220813 \
  vnmd/neurodesktop:20220813

Then inside the neurodesktop container run:


sudo apt update
sudo apt install libcudart10.1

For a GPU with Nvidia driver Version > 495.29.05:


wget https://developer.download.nvidia.com/compute/cuda/11.5.0/local_installers/cuda_11.5.0_495.29.05_linux.run
sudo sh ./cuda_11.5.0_495.29.05_linux.run

Running tensorflow (w/ GPU)

Using tensorflow (python)

conda install tensorflow-gpu
python
import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))

image

Using tensorflow (singularity container in neurodesktop)
singularity pull docker://tensorflow/tensorflow:latest-gpu
singularity run --nv tensorflow_latest-gpu.sif
python
import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))

image

Using an RDP Client

Startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 -p 3390:3389 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Open your RDP client and connect to Computer localhost:3390

Use the following details to login if prompted

username: user
password: password

Using VNC

To enable VNC and disable RDP, startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813 --vnc

To enable both VNC and RDP, startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813 --vnc --rdp

Using a VNC Client

Startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 -p 5901:5901 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813 --vnc

Open a VNC Client and connect to port 5901

1.2 - MacOS

Install neurodesktop on MacOS

Minimum System Requirements

  1. At least 3GB free space for neurodesktop base image
  2. An Intel Mac. M1/ARM Macs are not yet supported.
  3. Docker requirements. Details found under https://docs.docker.com/get-docker/

Quickstart

1. Install Docker

Install Docker from here: https://docs.docker.com/get-docker/

Docker for MacOS by default runs with 2GB Memory. For actual workloads, 4GB Memory minimum for docker is highly recommended

  1. Open the Docker Desktop and Navigate to the Resources tab. Instructions found at https://docs.docker.com/desktop/mac/#resources

  2. Increase the Memory slider from 2.00 GB to 4.00 GB (or greater)

  3. Increase Swap slider from 1GB to 2GB (or greater)

2. Run Neurodesktop

Create a local folder where the downloaded applications will be stored, e.g. ~/neurodesktop-storage

  1. Open a terminal, and type the folowing command to automatically download the neurodesktop container and run it
docker run --shm-size=1gb -it --privileged --name neurodesktop -v ~/neurodesktop-storage:/neurodesktop-storage -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

if you get errors in neurodesktop then check if the ~/neurodesktop-storage directory is writable to all users, otherwise run chmod a+rwx ~/neurodesktop-storage

  1. Once neurodesktop is downloaded i.e. guacd[77]: INFO: Listening on host 127.0.0.1, port 4822 is displayed in terminal, leave the terminal open and neurodesktop running (i.e., do not press CTRL+C)

  2. Open a browser and go to:

http://localhost:8080/#/?username=user&password=password
  1. Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”

  2. If it is the first time you use Neruodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.

  3. Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.

Deleting neurodesktop:

When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")

  1. Click on the terminal from which you ran neurodesktop

  2. Press control-C

  3. Type:

docker stop neurodesktop
  1. Type:
docker rm neurodesktop

Using an RDP Client

Startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v ~/neurodesktop-storage:/neurodesktop-storage -p 3390:3389 -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Open your RDP client and connect to Computer localhost:3390

Use the following details to login if prompted

username: user
password: password

Using VNC

To enable VNC and disable RDP, startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v ~/neurodesktop-storage:/neurodesktop-storage -e VNC_ENABLE=true -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Using a VNC Client

Startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v ~/neurodesktop-storage:/neurodesktop-storage -e VNC_ENABLE=true -p 5901:5901 -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Open a VNC Client and connect to port 5901

1.3 - Windows

Install neurodesktop on Windows

Minimum System Requirements

  1. At least 3GB free space for neurodesktop base image
  2. Docker requirements. Details found under https://docs.docker.com/get-docker/
  3. If installing docker using WSL, atleast 20GB space recommended for WSL with Ubuntu

Quickstart

1. Install Docker

Install Docker from here: https://docs.docker.com/get-docker/

2. Run Neurodesktop

Use one of the following options to run Neurodesktop:

Option 1: NeuroDesktop.exe

Download and run the following executable. Be aware: 1) The exe file can trigger your anti virus programs and we are working on this. 2) This exe will always download the latest version of neurodesk. For full reproducibility and control please choose Option 2 :) https://github.com/NeuroDesk/neurodesktop/raw/main/Windows_run_Neurodesk/NeuroDesktop.exe

Option 2: Using Terminal

  1. Open a terminal (e.g. Powershell), and type the folowing command to automatically download the neurodesktop container and run it
docker run --shm-size=1gb -it --privileged --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813
  1. Once neurodesktop is downloaded i.e. guacd[77]: INFO: Listening on host 127.0.0.1, port 4822 is displayed in terminal, leave the terminal open and neurodesktop running (i.e., do not press CTRL+C)

  2. Open a browser and go to:

http://localhost:8080/#/?username=user&password=password
  1. Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”

  2. If it is the first time you use Neruodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.

  3. Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.

  4. For an optimal experience, switch your browser to full-screen mode by following the instructions for your browser here: https://www.thewindowsclub.com/open-chrome-edge-or-firefox-browser-in-full-screen-mode

Deleting neurodesktop:

When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")

  1. Click on the terminal from which you ran neurodesktop

  2. Press control-C

  3. Type:

docker stop neurodesktop
  1. Type:
docker rm neurodesktop

Using an RDP Client

Startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -p 3390:3389 -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Open Windows Remote Desktop Connection and connect to Computer localhost:3390 as shown below.

win-rdp-1

Resolution and multi-monitor settings can be set from the Display tab.

Once ready, click Connect. This will take you to the following prompt

win-rdp-1

Use the following details to login

Session: Xorg
username: user
password: password

Using VNC

To enable VNC and disable RDP, startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -e VNC_ENABLE=true -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Using a VNC Client

Startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -e VNC_ENABLE=true -p 5901:5901 -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Open a VNC Client and connect to port 5901

1.4 - HPC

Run neurodesktop in a high performance computing environment

One way of running this project on HPCs is via https://www.neurodesk.org/docs/neurocommand/getting-started/linux/

1.5 - Nectar Virtual Desktop Service

Run neurodesktop in the Nectar Virtual Desktop Service

This option is only available to Australian researchers.

Go to https://desktop.rc.nectar.org.au/

Click on “Sign in”.

Choose the AAF option.

Choose your instituion from the list.

Provide your email address and password.

Click on “EXPLORE”.

Click “VIEW DETAILS” under Neurodesktop: image

Click “CREATE DESKTOP +” button on the top right corner.

Choose the desired availability zone.

Wait until everything is completed: image

Click “OPEN DESKTOP ->”: image

To launch the various applications available in Neurodesktop, follow the instructions here: https://www.neurodesk.org/docs/neurodesktop/whats-next/#how-to-launch-applications

There are a few little differences between the open-source version of Neurodesk and what’s hosted on Nectar VDI:

  1. There is no /neurodesktop-storage folder.
  2. Files uploaded via drag and drop do not get stored on the desktop but in /home/vdiuser/thinclient_drives/GUACFS

Good luck!

1.6 - Visual Studio Code

Guide connecting your VS Code environment to Neurodesktop

Following guide is for connecting to a Neurodesktop using a VS Code installation running on your host machine.

Additional instructions if your Neurodesktop is running remotely (i.e. Cloud, HPC, VM)

Pre-requisites

Visual Studio Code (https://code.visualstudio.com) installed on your host. Standalone version should work fine

Install the following VS Code extensions:

For Remote servers

Open VS Code

Open the Command Palette (Ctrl+Shift+P)

Find Remote-SSH: Connect to Host... and select your remote host

More information on remote hosts available at https://code.visualstudio.com/docs/remote/ssh

This will open a new VS Code instance connected to the remote host via SSH. You may close the previous VS Code instance.

Follow the steps in the next section using the new VS Code instance

Connecting to Neurodesktop

Open VS Code and open a Folder (File > Open Folder)

This can be any folder (e.g. home or project folder). VS Code runs into errors if no folder is opened.

Open the Command Palette (Ctrl+Shift+P).

Select Remote-Containers: Attach to Running Container from the dropdown panel

Start typing in ’neurodesktop. Select /neurodesktop from the list

This should open a VS Code Window connected to the neurodesktop as a Dev Container.

First time connection will take about a minute, as VS code has to install the VS Code server onto the container. Repeat connections should be faster

First time connection

First time connection will default to using neurodesktop root user. We want to default connection to be as the normal user to avoid permission issues. To check which user is being use, open the terminal in the neurodesktop VS Code and check if the user is user or root

Follow the following steps to configure your VS Code to connect to neurodesktop as normal user by default

Open the Command Palette (Ctrl+Shift+P).

Select Remote-Containers: Open Container Configuration File from the dropdown panel

This will open a neurodesktop%3alatest.json file. Overwrite the file with the following contents

{
	"workspaceFolder": "/home/user",
	"remoteUser": "user"
}

Close this VS Code window. Use steps in previous section to connect normally

Useful Additions

A plugin to view neuroimaging data inside VScode is also available: image

1.7 - Cloud

Run neurodesktop using Oracle or Azure cloud computing

Minimum System Requirements

  1. At least 3GB free space for neurodesktop base image
  2. Docker requirements. Details found under https://docs.docker.com/get-docker/

Quickstart

1. Connect to cloud server

On the computer from which you want to access Neurodesktop, open an SSH connection to your cloud instance with port forwarding (USER should be substituted with a username that has admin privileges on the cloud instance, and IP should be substituted with the IP address of the cloud instance)

ssh -L 8080:127.0.0.1:8080 USER@IP

2. Install Docker

Install Docker on the cloud instance from here: https://docs.docker.com/get-docker/. Additional information available here: https://www.neurodesk.org/docs/neurodesktop/getting-started/linux/#installing-docker

3. Run Neurodesktop

Create a local folder ~/neurodesktop-storage on the cloud instance to store persistent data (data that will not disappear if neurodesktop is stopped)

Option 1: NeuroDesktop.run

Download and run the following executable on the cloud instance https://github.com/NeuroDesk/neurodesktop/raw/main/Linux_run_Neurodesk/NeuroDesktop.run

Option 2: Using Terminal

  1. Open a terminal on the cloud instance, and type the folowing command to automatically download the neurodesktop container and run it
sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813
  1. Once neurodesktop is downloaded to the cloud instance (guacd[77]: INFO: Listening on host 127.0.0.1, port 4822 is displayed in terminal), leave the terminal open and neurodesktop running (i.e., do not press CTRL+C)
  1. If it is required to set up an SSH tunnel to access the cloud instance, please set up such a tunnel from the computer from which you want to access Neurodesktop (e.g. ssh -L 8080:127.0.0.1:8080 USER@IP)

  2. Open a browser on the computer from which you want to access Neurodesktop, and go to:

http://localhost:8080/#/?username=user&password=password

If the computer runs Linux, check specific instructions at https://www.neurodesk.org/docs/neurodesktop/getting-started/linux/, Option 2, Step 3.

  1. Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”

  2. If it is the first time you use Neruodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.

  3. Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.

  4. For an optimal experience, switch your browser to full-screen mode by following the instructions for your browser here (except Mac where full-screen mode is built-in): https://www.thewindowsclub.com/open-chrome-edge-or-firefox-browser-in-full-screen-mode

Deleting neurodesktop:

When done processing your data it is important to stop and remove the container - otherwise the next start or container update will give an error ("… The container name “/neurodesktop” is already in use…")

  1. Click on the terminal from which you ran neurodesktop

  2. Press Ctrl-C

  3. Run:

sudo docker stop neurodesktop && sudo docker rm neurodesktop

Portforwarding to an iOS ipad

You can also connect to this cloud instance from your iOS device :) For this install https://webssh.net/documentation/help/networking/port-forwarding/ and create a tunnel (the tool is free for one connection). Start the docker container in a screen session and then connect to it from your ios device in the browser.

Cloud-provider specific Tutorials

Cloud providerlink
Oraclehttps://mri.sbollmann.net/index.php/2020/12/08/run-neurodesk-on-oracle-cloud-free-tier/
Azurehttps://henryjburg.medium.com/neurodesk-running-on-azure-3e38c590a152

Using an RDP Client

Open an SSH connection to your cloud instance with the following command

ssh -L 3390:127.0.0.1:3390 USER@IP

Startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 -p 3390:3389 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Open your RDP client and connect to Computer localhost:3390

Use the following details to login if prompted

username: user
password: password

Using VNC

To enable VNC and disable RDP, startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813 --vnc

To enable both VNC and RDP, startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813 --vnc --rdp

Using a VNC Client

Startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)"\
  -p 8080:8080 -p 5901:5901 \
  -h neurodesktop-20220813 vnmd/neurodesktop:20220813 --vnc

Open a VNC Client and connect to port 5901

1.8 - Play

Run a demo of neurodesktop without installing anything

Choose the link below closest to your location for your own instance of Neurodesk on your browser running on Oracle cloud resources.

LocationNeurodesk Play link
Australia Easthttps://play.neurodesk.org/v2/gh/neurodesk/jupyter-neurodesktop-image/main?urlpath=neurodesktop
US Westhttps://play-phoenix.neurodesk.org/v2/gh/neurodesk/jupyter-neurodesktop-image/main?urlpath=neurodesktop
US Easthttps://play-ashburn.neurodesk.org/v2/gh/neurodesk/jupyter-neurodesktop-image/main?urlpath=neurodesktop
Germany Centralhttps://play-frankfurt.neurodesk.org/v2/gh/neurodesk/jupyter-neurodesktop-image/main?urlpath=neurodesktop

You can upload data to the desktop by simply drag-and-dropping files on the browser window. Data uploaded during your session are stored on Oracle Cloud, and will be automatically deleted at the end of the session. To download your files before deletion: You need to open the guacamole settings by pressing CTRL-ALT-SHIFT (Control-Command-Shift on Mac). This will open a menu on the side:

{A12EDB8A-3D01-4524-A7B5-24E5E94FB418}

where you can click on “Shared Drive”:

{645953A1-5D11-48C7-9DFB-25D4339EEA34}

and a click (or double clink on Mac) on the file will start the download.

You can browse into folders in the shared drive by clicking (double clicking on Mac) on them. To get back to the base of the shared drive, press on the drive icon in the top left of the side menu (just below the “Shared Drive” title).

To close the side menu, click on CTRL-ALT-SHIFT once more (Control-Command-Shift on Mac).

2 - What's next?

Congratulations! You’ve installed Neurodesktop. What happens next?

Now that you’ve installed and launched neurodesktop, you should see a virtual desktop environment in your browser, which might look something like this:

desktop

In this linux desktop environment, you can access the menu, launch programs, write analysis code, use version control software (i.e. git) and develop analysis pipelines as though you were on your own computer.

Release

Keep a note of the release date of the container image that you installed. Regardless of what operating system you installed neurodesktop into, the release date would have been at the end of the docker run command:

version

We regularly update neurodesktop to make sure it’s running well and has up-to-date software. You can check the Release History page for details of previous releases. If you’d like to update your container at any time, simply switch out the release number for the version you would like. If you’ve finished working on an analysis pipeline and would like to share it with others, you can point them toward the stable release number that you worked in. That way anyone, on any computer around the world can replicate your analysis pipeline in the exact same computing environment that you developed it in.

Video tutorial

Click here to watch a 2 minute tutorial video from OHBM 2021

How to access files from your Host computer

There are various ways of connecting your data to to Neurodesktop. For more information see our Storage section: Storage

How to launch applications

Click on the Launcher icon in bottom-left corner, navigate to the “Neurodesk” menu and then to the relevant submenu (or “All Applications” for an alphabetical list of all applications). Navigate to the desired application, and then click on a menu entry. If it is the first time you launch an application, it may take a few seconds until it starts (please be patient!).

If you choose a menu entry with “GUI” at the end (e.g., fsleyesGUI 6.0.3), the main GUI interface of the application will open.

If you choose a menu entry without “GUI” at the end (e.g., fsl 6.0.3), a terminal window will open, and you can use it to run any of the utilities packaged with the application, including the graphical utilities (e.g., typing “fsl” to run FSL’s main menu). Please be patient when running a utility for the first time; Neurodesk is using a clever system that only downloads the utilities that you are actually using, but this may incur a short delay on the order of seconds. Also notice that the terminal that opens only allows to run utilities from the one application chosen in the menu. To be able to run utilities from multiple applications in the same terminal (or in the same script), please open a separate terminal by clicking on the terminal icon in the bottom toolbar of Neurodesktop. You will then be able to use the ‘module’ command in order to load the desired applications.

How top copy and paste text

You can copy and paste text within Neurodesktop and between Neurodektop and your host computer using the regular keyboard shortcuts (CTRL+C, CTRL+X, and CTRL+V). Note however that some applications (e.g., command-line terminal) are using other keyboard shortcuts. You can usually find them in the “Edit” menu of the relevent application.

Note for Mac Users: You will need to use a combination of CTRL and Command shortcuts in order to copy and paste text between Neurodesktop and the host computer. For example, copy text from your Mac with Command+C and then paste it into Neurodesktop using CTRL+V. For the other way around, you’d use CTRL+C in Neurodesktop and then Command+V on the Mac.

How to keep your modifications in the container

We designed neurodesk with reproducibility as a main goal, so the desktop containers should not be modified if one aims for full reproducibility. However, there is one good option to keep your settings across different container versions: You can write a shell script that installs additional packages and modifies the environment so it’s perfect for you. This script can then be re-executed in a new desktop version and will enable a reprudcible customization.

Another option is to “save” your docker container including all changes you made. This could be useful when your changes are too difficult to write a shell script or when you do not care about reproducibilty as much and you just want to get the job done. To do this you can commit (https://docs.docker.com/engine/reference/commandline/commit/) your container and by uploading the container to your own docker hub you could even share it.

How to force a complete container download to your system

To increase speed and reliability of Neurodesktop we mount the application containers from a CVMFS mount and download only the files required to run your current task. Although we aim to keep everything on there reproducible, there might be a reason that you want to fully download the containers to your system. You can force this behaviour by adding another parameter to the docker call: -e CVMFS_DISABLE=true

For windows an example would look like this:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -e CVMFS_DISABLE=true -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

3 - What's in the box?

The software available in neurodesktop

Neurodesktop comes with the essential software required for neuroimaging data analysis pre-installed. Each release is built with the most recent version of these packages available at the build date. Some example packages include:

  • Editors and Programming (can be found in menu, or launched from command line by typing their name):
    • code (Visual Studio Code)
    • gedit (simple visual editor)
    • emacs
    • vim
    • python
    • git
  • Workflow systems:
    • Nipype (including GraphVis)
  • Data Syncronisation tools: (See our Storage section for more information: Storage)
  • System Management:
    • Lmod (inlcuding Lua)
    • Singularity
    • Htop
  • Misc
    • Imagemagic
    • Firefox
    • OpenSSH client

The neurodesktop environment is built to be light and fast to download and start-up. Most additional programs are therefore downloaded when they are first used. A list of these packages can be found here

4 - Storage

Add storage to Neurodesktop

Drag and Drop support

You can drag-and-drop files into the browser window to get files into the Neurodesktop. This will then start a file upload:

{538BB51E-0FEB-46EA-B1B8-FDF122776735}

To download files from the desktop using the same mechanism you need to open the guacamole settings by pressing CTRL-ALT-SHIFT (Control-Command-Shift on Mac). This will open a menu on the side:

{A12EDB8A-3D01-4524-A7B5-24E5E94FB418}

where you can click on “Shared Drive”:

{645953A1-5D11-48C7-9DFB-25D4339EEA34}

and a click (or double clink on Mac) on the file will start the download.

You can browse into folders in the shared drive by clicking (double clicking on Mac) on them. To get back to the base of the shared drive, press on the drive icon in the top left of the side menu (just below the “Shared Drive” title).

To close the side menu, click on CTRL-ALT-SHIFT once more (Control-Command-Shift on Mac).

Data directory connection to the host computer

If you are running Neurodesktop on your own hardware there will be a direct connection between the “Storage” folder on the Destkop, which is a link to “/neurodesktop-storage” and a “neurodesktop-storage” folder on your C-drive (Windows) or home directory (Mac/Linux). This connection can be used for data processing and data transfer.

Mounting external storage on your host-computer

The -v C:/neurodesktop-storage:/neurodesktop-storage part of the docker command links the directory “neurodesktop-storage” on the “C drive” of your Windows computer to the directory /neurodesktop-storage inside the Desktop environment. Everything you store in there will be available inside the desktop and on the host computer. You can also mount additional directories by adding another -v parameter set (e.g. -v D:/moredata:/data) - this will mount the directory moredata from your D drive to /data inside neurodesktop. Improtant: the mountpoint inside neurodesktop should be named /data (or anything from this list: https://github.com/NeuroDesk/neurocontainers/blob/master/recipes/globalMountPointList.txt) - otherwise most of the tools will not be able to access the data.

Here is an example for Windows adding another storage directory:

docker run --shm-size=1gb -it --privileged --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -v D:/moredata:/data -p 8080:8080 -h neurodesktop-20220813 vnmd/neurodesktop:20220813

Cloud-storage

Another way to get your data into Neurodesktop is to use a cloud storage provider like CloudStor, Dropbox, OneDrive and their sync tools like OwnCloud, Nextcloud or very flexible tools like rclone or davfs2. Another good option could be to utilize Globus for large amounts of data.

Nextcloud and Owncloud desktop clients

Under the menu item “Accessories” you can find “Nextcloud” and “ownCloud” desktop sync clients that you can configure with your cloud service accounts.

To connect for example to your AARNET cloudstor account you can start the ownCloud client and enter the Server Address:

https://cloudstor.aarnet.edu.au/plus/

Then generate an app-password here: https://cloudstor.aarnet.edu.au/plus/settings/personal?sectionid=security

Mounting webdav storage using davfs2

Another option is to directly mount webdav storage. Here is an example how to mount CloudStor into Neurodesktop:

sudo mount -t davfs https://cloudstor.aarnet.edu.au/plus/remote.php/webdav/ /data/

It then asks you for a username and password, which you can generate here: https://cloudstor.aarnet.edu.au/plus/settings/personal?sectionid=security

Rclone

Rclone is a command line tool that enables the interaction with various cloud services. Here is an example how to setup rclone with CloudStor Aarnet:

  • start the configuration in a terminal window rclone config
  • Create a new remote: n
  • Provide a name for the remote: CloudStor
  • For the “Storage” option choose: webdav
  • As “url” set: https://cloudstor.aarnet.edu.au/plus/remote.php/webdav/
  • As “vendor” set OwnCloud: 2
  • Set your CloudStor username after generating an access token https://cloudstor.aarnet.edu.au/plus/settings/personal?sectionid=security
  • Choose to type in your own password: y
  • Enter the Password / Token from the CloudStor App passwords page and confirm it again:
  • Leave blank the bearer_token: <hit Enter>
  • No advanced config necessary: <hit Enter>
  • accept the configuration: <hit Enter>
  • Quit the config: q
  • Now we can download data to the HPC easily: rclone copy --progress --transfers 8 CloudStor:/raw-data-for-science-paper .
  • or upload data to CloudStor: rclone copy --progress --transfers 8 . CloudStor:/data-processed

Globus

We also provide the globus client, so you can transfer large amounts of data between globus endpoints and Neurodesktop. You can configure it by running:

/opt/globusconnectpersonal/globusconnectpersonal-*/globusconnectpersonal

Once authenticated you can go to the globus file-manager https://app.globus.org/file-manager and your neurodesktop instance will be an endpoint for globus.

Mount volume using SSHFS

It is theoretically possible to mount an SSH target inside Neurodesktop, but it’s not a very reliable way of mounting storage:

sshfs -o allow_root USER@TARGET_HOST:TARGET_PATH SOURCE_PATH

A better option is to use scp and copy data from an SSH endpoint:

scp /neurodesk/myfile user@remoteserver:/data/

An alternative is to mount the SSHFS target into a parent directory on your local machine or VM and then use the -v option in the docker run command to bind the parent directory of the SSHFS mount. NOTE: the SSHFS has to be mounted to a subdirectory inside a parent directory which is then bound to the docker container. If you directly bind to the mounted directory itself, your Neurodesktop container will stop being able to access it if the SSHFS mount disconnects and will not be able to access it again without restarting the Neurodesktop container.

For example, on a local Linux machine or VM:

sshfs -o allow_root USER@TARGET_HOST:TARGET_PATH/MyData SOURCE_PATH/SSHFS_Mounts/MyData

Then add the following line to the docker run command when starting Neurodesktop (note the rshared flag):

-v /SSHFS_Mounts:/data:rshared \

TIP: If you use key pair authentication instead of password for your SSHFS mount, you can use the reconnect flag to reconnect automatically if the connection drops:

sshfs -o IdentityFile=~/.ssh/id_rsa,allow_root,ServerAliveInterval=5,ServerAliveCountMax=3 USER@TARGET_HOST:TARGET_PATH/MyData SOURCE_PATH/SSHFS_Mounts/MyData

5 - Troubleshooting

Are you experiencing issues with neurodesktop?

Neurodesk is an open-source project that is always evolving. If you are experiencing an issue not listed here, please open a new issue, so that we can aim to solve it and update our help documentation.

To ask questions or suggest new features, join the discussion on github.

I cannot copy and paste text within Neurodesktop using keyboard shortcuts

If you’re using Mac, you might be trying to use Mac keyboard shortcuts, but Neurodesktop is using Linux keyboard shortcuts (CTRL+C and CTRL+V)

If you use the terminal, please see “I fixed my internet browser clipboard, but copy or paste still do not work in the terminal” below.

Copying text from my host computer and pasting it inside Neurodesktop doesn’t work in Firefox

This is a “feature” of firefox and you can disable this “feature”:

  • navigate to about:config and “Accept the Risk and Continue” (“about:config” needs to be entered in the address bar of firefox and hit enter)
  • now search for clipboard and then set the following to “true”:
    • dom.events.asyncClipboard.clipboardItem
    • dom.events.asyncClipboard.read
    • dom.events.testing.asyncClipboard

Then close firefox and restart. Then the clipboard should work as one would expect.

If the clipboard still does not work, check “I fixed my internet browser clipboard, but …” sections below.

Copy and paste between my host computer and Neurodesktop (or vice versa) doesn’t work in Chrome or Edge

The browsers have a security feature to protect you from something stealing your clipboard content. Depending on your security settings you have to enable it explicitly - it’s a little icon in the browser address bar that looks like a clipboard.

After pressing the icon, you should choose the option shown below in the dialog that opens. After pressing “Done”, close the current browser tab and open a new one for the changes to take effect.

image

If the clipboard still does not work, check “I fixed my internet browser clipboard, but …” sections below.

I fixed my internet browser clipboard, but copy or paste still do not work in the terminal

The terminal is using special keyboard shortcuts, Shift+CTRL+C for copy, and Shift+CTRL+V for paste. Alternatively, you can copy and paste text by using the terminal’s “Edit” menu.

I fixed my internet browser clipboard, but copy or paste still do not work in the file browser

The copy and paste options in the “Edit” menu of the file browser are used to copy and paste files, not text. To copy and paste text from/into the file browser application (e.g., copy a path into the path field in the top), use the CTRL+C and CTRL+V keyboard shortcuts.

I fixed my internet browser clipboard, but copy or paste still do not work in a specific/all applications

If you’re using Mac, you might be trying to use Mac keyboard shortcuts, but Neurodesktop is using Linux keyboard shortcuts. For more details, read the “Note for Mac users” here.

If it still does not work, or if your host is Windows or Linux, please report the problem and we will do our best to help you:

  1. Copy some text from your host computer (CTRL+C, or Command+C)
  2. Open the Mousepad text editor in Neurodesktop (Start button –> “Accessories” —-> “Mousepad”)
  3. Try to paste the text using the menu option “Edit” –> “Paste”
  4. Try to paste the text again using CTRL+V
  5. If you don’t have one already, please create a Github account here
  6. Go to our discussion forum here
  7. If you are not logged into Github, please log in (upper right corner)
  8. Press “New Discussion” button
  9. In the message that you write, please specify your operating system, your internet browser, the application in question, and if you can copy/paste to Mousepad and how?

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.

This is usually a docker-related error, not related to neurodesktop itself. To troubleshoot docker, we can try a simpler container first:

docker run hello-world

Try the following solutions (in this order, until the above command works)

  1. Win/Mac: Open docker GUI and accept T&Cs. Check that the docker engine is running
  2. Linux: Make sure you started the docker daemon (sudo systemctl start docker)
  3. Add your user to the OS docker group (sudo usermod -aG docker $USER)
  4. docker.sock permissions need to be changed (sudo chown root:docker /var/run/docker.sock)
  5. Close and open the terminal and retry.
  6. Log out and login again, or restart the machine (current user environment doesnt fully know docker is running)

Windows users: WSL not installed properly

The Docker engine relies on the Windows subsystem for Linux (WSL) to run on a windows machine.

If WSL is properly installed, the Resources tab of the Docker settings should look something like this:

Docker_WSL_correct

However, if WSL is missing or incorrectly configured, the Resources tab of the Docker settings may look something like this:

Docker_WSL_incorrect

If this is the case, follow the manual install instructions to install WSL 2 (including installation of Ubuntu through Microsoft Store).

Windows users: Not enough free space on the partition in Windows and WSL2

This could help: https://yjmantilla.github.io/tutorials/wsl2-move-vhdx.html

Windows users: Failure to connect to Neurodesktop in Firefox

We recommend using Microsoft Edge or Google Chrome to access Neurodesktop.

Trouble installing neurodesk images

This may be a memory issue. First, ensure that there is enough free space on the disk. If there is, try resetting docker settings and data. To do this:

  1. Open the docker engine
  2. Navigate to “Troubleshooting” (the bug icon in the top right).
  3. Click “Reset to factory defaults”

Docker_troubleshooting

If you are still experiencing issues after this, you may need to update docker to the latest version. This can be achieved through “settings” in the docker engine, or (on windows) by right clicking on the docker tray icon:

Docker_update

I got an error message ‘X killed’ or not enough memory

This may be due to Docker not having access to enough RAM from your host computer.

If you are using Docker on MacOS

  1. The memory amount is managed via the Docker settings: image

If you are using Docker on Windows 10 with the WSL2 backend

then this is managed by Windows settings. Try the following steps to check how much RAM Docker has access to and increase the amount if necessary.

  1. Run Docker
  2. Open a terminal (ie. Powershell) in the PC you want to use to run Neurodesktop (not in Neurodesktop itself) and type the following command:
docker info

This will generate information about your Docker installation (make sure Docker is running during this step)

  1. Look for the line that says
Total Memory: **.**GiB
  1. If this value is ~2GB, try increasing it*:
    [wsl2]
    memory=32GB
    
    • Quit Docker (make sure it’s not running in the background, ie. system tray, check task manager)
    • In the terminal, run the following command
    wsl --running --list
    
    This will list any running distributions. For the update to be successful, WSL needs to have comletely stopped running (ie. no distributions running)
    • Restart Docker and rerun steps 1-3 to confirm it was successful

If you are not using WSL2, you can check and manage your RAM allocation in the Docker desktop application.

  1. Open the Docker application and navigate to settings > resources > advances
  2. Scroll down to the Memory option and use the sliding bar to adjust the setting
  3. Click apply and restart

*RAM requirements will vary based on the tools/data you are using. If the system you’re using has limited RAM, test out a few different amounts by running the above steps and then your analyses in Neurodesktop. Version 20220208 onwards has a memory monitor in the taskbar - you can use this to check how much memory Neurodesktop has access to and how much is being used by the analyses being run.

6 - Release History

Previous releases of neurodesktop

development

  • updated qsmxt to 1.1.13 (contributed by Ashley)
  • added nipype 1.8.3 (contributed by Steffen)
  • added mneextended 1.1.0 (contributed by David)
  • added new tool category “workflows”
  • added new CVMFS mirror server in Phoenix
  • added mimilist types so that nii/minc files now open in the respective applications

20220813

  • updated qsmxt to 1.1.12 (contributed by Ashley)
  • updated 3D Slicer to 5.0.3 and included MONAI Label (contributed by Xincheng)
  • added Matlab 2022a (contributed by Oren)
  • updated AFNI to 22.1.14 (contributed by Steffen)
  • updated Spinal Cord Toolbox to 5.7 (contributed by Steffen)
  • updated Oshyx to 0.4 (contributed by Jeryn)
  • updated freesurfer to 7.3.2 (contributed by Steffen)
  • added CVMFS mirror server in Perth and cleaned up server list to account for DNS geo location steering (contributed by Steffen)

20220701

  • added laynii 2.2.1 - layer fMRI toolbox (contributed by Renzo Huber)
  • added fieldtrip 20220617 - eeg processing (contributed by David White)

20220329

  • added bidscoin 3.7.0 (converting data to bids) contributed by Oren
  • added sigviewer 0.6.4 (viewing electrophysiological data) contributed by Tom
  • added niftyreg 1.4.0 (image registration tool) contributed by Steffen
  • added mne 1.0.0 (EEG processing pipeline) contributed by David

20220302

  • update of ROMEO (phase unwrapping) to latest version 3.2.8
  • update of QSMxT (automated end-to-end QSM procerssing) to latest version 1.1.10
  • added mritools 3.3.0 (includes clearswi 1.0.1, mcpc3ds 0.1.0, romeo 3.2.8 as compiled binaries)

20220222

  • update for PhysIO toolbox (physiological noise correction for fMRI) to r2021a including the latest SPM r8224
  • update of lcmodel to include basis sets for 1.5-9.4T
  • added a memory display plugin to illustrate how much memory is available to the container and how much is consumed
  • added a version checker to help with identifying if a new version is available
  • added file upload via guacamole (+ update of guacamole to 1.4) - users can now drag and drop their files onto guacamole and they get copied to the desktop

20220128

  • update of Spinalcordtoolbox to 5.5
  • update of CAT12 to r1933

20220121

  • MNE Python 0.23.4 container including VScode and extensions
  • VScode container including Python/Julia Extensions and singularity to test “Inception Mode” (Running singularity containers withtin singularity containers)
  • update of fsl to 6.0.5.1
  • added CAT12 (a software that allows estimation of tissue volumes (and additional surface parameters such as cortical thickness, gyrification or fractal dimension) for different volume and surface-based atlas maps)

20220111

  • a deep learning based vessel segmentation algorithm “vesselapp” was added in version 0.3.1
  • palm - Permutation Analysis of Linear Models - was added in version alpha119
  • niistat running in octave was added with version 1.0.20191216
  • MRIcroGL was updated to a version with included python support, so the scripting is now working
  • rabies - Rodent Automated Bold Improvement of EPI Sequences was added with version 0.3.5
  • oshyx was updated to 0.3

20211220

  • neurodesktop can now be accessed via native RDP client as well (e.g. for multi-monitor support): https://www.neurodesk.org/docs/neurodesktop/getting-started/windows/#using-an-rdp-client
  • there is a new Help button in the menu :)
  • updates of ants 2.3.4 (now includes Scripts as well, including antsCookTemplatePriors.sh) + newly added version 2.3.5
  • new version of QSMxT 1.1.9 20211219
  • new version of Spinal Cord Toolbox 5.4
  • new tools: MRIcroGL and surfice - fantastic viewers for neuroimaging data

20211207

  • Physio toolbox compiled and added to SPM + update of SPM
  • added brainstorm
  • new neurodesktop container management scripts for Linux, Mac and Windows: https://github.com/NeuroDesk/neurodesktop
  • added fieldtrip
  • Datalad is now in the main image, so datalad run should work
  • added Oshy-X segmentation tool
  • updated freesurfer 7.2.0

20211028

  • added EEGLAB

20211018

  • added Rstudio, R and multiple R packages (plotly, car, tidyverse, …)
  • added ClearSWI and ROMEO for MRI phase processing (including new Tutorials: https://www.neurodesk.org/tutorials/phase_processing/)
  • added more categories in applications menu (Body, Electrophysiology, Hippocampus, Phase Processing, Rodent Imaging, Shape Analysis, Spine, Statistics)
  • bugfix: improved startup time of the desktop container (miniconda in homedirectory was causing chmod slowdown)
  • bugfix: ssh, vnc and rdp servers are now restarted in case the container was stopped and started again (e.g. on Standby)

20210929

  • fixed naming of aidmri to aidamri and added new category “Rodent Imaging”
  • updated all tool icons and updated neurodesk icon including background image
  • VScode now stores settings in persistent storage /neurodesktop-storage and with this keeps extensions and settings across different neurodesktop versions
  • docker layers are now cached, so updating the desktop to the next version is very fast and consumes less disk space locally
  • default theme of terminal changed from Solarized to Tango as the old theme was hiding information in tools like htop (same font colour on same background…)

20210923

  • removed faulty mriqc 0.15.2 container
  • neurodesk.github.io is now starting page in firefox browser

20210918

  • added mriqc 0.16.1 and mrtrix 3.0.3

20210917

  • included more tools for connecting to cloud storage services (rclone, owncloud, nextcloud, davfs2, globus). For more info: Storage
  • styling of desktop interface, including background wallpaper and colour scheme in terminal window
  • new categories in menu system (visualization) and added more categories to tools

20210916

  • This is the first version of the newly renamed and rebuild neurodesktop (previously vnm and neuromachine)
  • containers are mounted by default from CVMFS, but this can be deactivated by adding -e CVMFS_DISABLE=true to the docker call