Getting Started

• 1: Linux
• 2: MacOS
• 3: Windows
• 4: HPC
• 5: Nectar Virtual Desktop Service
• 6: Visual Studio Code
• 7: Cloud
• 8: Play

1 - 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-20221129 vnmd/neurodesktop:20221129

2. 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)

3. Open a browser and go to:

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

"http://localhost:8080 wants to
See text and images copied to the clipboard".

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

5. 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.

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

7. 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

4. 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)" \
  --gpus all \
  -p 8080:8080 -h neurodesktop-20221129 \
  vnmd/neurodesktop:20221129

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')))

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')))

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-20221129 vnmd/neurodesktop:20221129

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-20221129 vnmd/neurodesktop:20221129 --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-20221129 vnmd/neurodesktop:20221129 --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-20221129 vnmd/neurodesktop:20221129 --vnc

Install the Tiger VNC client

sudo apt install tigervnc-client

Run the VNC Client and connect to localhost::5901

Enter password and click Ok.

2 - 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-20221129 vnmd/neurodesktop:20221129

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

2. 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)

3. Open a browser and go to:

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

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

4. 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.

5. 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

4. 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-20221129 vnmd/neurodesktop:20221129

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-20221129 vnmd/neurodesktop:20221129

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-20221129 vnmd/neurodesktop:20221129

Open a VNC Client and connect to port 5901

3 - 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-20221129 vnmd/neurodesktop:20221129

2. 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)

3. Open a browser and go to:

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

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

5. 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.

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

7. 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

4. 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-20221129 vnmd/neurodesktop:20221129

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

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

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

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 -p 8080:8080 -h neurodesktop-20221129 vnmd/neurodesktop:20221129 --vnc 

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 -p 5901:5901 -p 8080:8080 -h neurodesktop-20221129 vnmd/neurodesktop:20221129 --vnc 

Download the Tiger VNC client (vncviewer64-1.12.0.exe) from https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/

Run the VNC Client and connect to localhost::5901

Enter password and click Ok.

4 - HPC

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

5 - 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:

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

Choose the desired availability zone.

Wait until everything is completed:

Click “OPEN DESKTOP ->”:

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!

6 - Visual Studio Code

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:

• Docker extension (Required)
• Remote development extension pack. Includes the following extensions
  • Remote - Containers (Required)
  • Remote - SSH (For remote servers)
  • Remote - WSL (For windows hosts)

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:

7 - Cloud

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-20221129 vnmd/neurodesktop:20221129

2. 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)

3. 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)

4. 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.

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

6. 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.

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

8. 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

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-20221129 vnmd/neurodesktop:20221129

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-20221129 vnmd/neurodesktop:20221129 --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-20221129 vnmd/neurodesktop:20221129 --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 --network host \
  -h neurodesktop-20221129 vnmd/neurodesktop:20221129 --vnc

Download the Tiger VNC client from https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/

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

ssh -L 5901:127.0.0.1:5901 USER@IP

Run the VNC Client and connect to localhost::5901

Enter password and click Ok.

8 - Play

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

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:

where you can click on “Shared Drive”:

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).