This the multi-page printable view of this section. Click here to print.
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
- At least 3GB free space for neurodesktop base image
- 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/. Additional information available below
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
- 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-20220329 vnmd/neurodesktop:20220329
chmod a+rwx ~/neurodesktop-storage
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)Open a browser and go to:
http://localhost:8080/#/?username=user&password=password
If using Chrome, a pop-up may open with the text:
"http://localhost:8080 wants to
See text and images copied to the clipboard".
You should press “Allow”
Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
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.
Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.
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…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.Click on the terminal from which you ran neurodesktop
Press
Ctrl-C
Run:
docker stop neurodesktop
- 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-20220329 \
vnmd/neurodesktop:20220329
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-20220329 vnmd/neurodesktop:20220329
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-20220329 vnmd/neurodesktop:20220329 --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-20220329 vnmd/neurodesktop:20220329 --vnc --rdp
VNC allows for multiple desktop connections to same instance
Note: Neurodesktop VNC on the browser currently does not support auto-resolution
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-20220329 vnmd/neurodesktop:20220329 --vnc
Open a VNC Client and connect to port 5901
2 - MacOS
Minimum System Requirements
- At least 3GB free space for neurodesktop base image
- An Intel Mac. M1/ARM Macs are not yet supported.
- 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
Open the Docker Desktop and Navigate to the Resources tab. Instructions found at https://docs.docker.com/desktop/mac/#resources
Increase the Memory slider from 2.00 GB to 4.00 GB (or greater)
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
- 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-20220329 vnmd/neurodesktop:20220329
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
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)Open a browser and go to:
http://localhost:8080/#/?username=user&password=password
Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
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.
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…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.Click on the terminal from which you ran neurodesktop
Press control-C
Type:
docker stop neurodesktop
- 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-20220329 vnmd/neurodesktop:20220329
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-20220329 vnmd/neurodesktop:20220329
VNC allows for multiple desktop connections to same instance
Note: Neurodesktop VNC on the browser currently does not support auto-resolution
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-20220329 vnmd/neurodesktop:20220329
Open a VNC Client and connect to port 5901
3 - Windows
Minimum System Requirements
- At least 3GB free space for neurodesktop base image
- Docker requirements. Details found under https://docs.docker.com/get-docker/
- 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
- 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-20220329 vnmd/neurodesktop:20220329
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)Open a browser and go to:
http://localhost:8080/#/?username=user&password=password
Note
We do not recommend the use of the Firefox browser for accessing Neurodesktop on Windows 10, as firefox is not able to access localhost where neurodesk is running.Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
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.
Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.
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…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.Click on the terminal from which you ran neurodesktop
Press control-C
Type:
docker stop neurodesktop
- 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-20220329 vnmd/neurodesktop:20220329
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 -e VNC_ENABLE=true -p 8080:8080 -h neurodesktop-20220329 vnmd/neurodesktop:20220329
VNC allows for multiple desktop connections to same instance
Note: Neurodesktop VNC on the browser currently does not support auto-resolution
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-20220329 vnmd/neurodesktop:20220329
Open a VNC Client and connect to port 5901
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/NZ researchers.
Go to https://desktop.rc.nectar.org.au/
Click on “Sign in”.
Choose the AAF option if you have an Australian university email or the NZ option if you have a New Zealand university email.
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
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
orroot
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
- At least 3GB free space for neurodesktop base image
- 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
- 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-20220329 vnmd/neurodesktop:20220329
chmod a+rwx ~/neurodesktop-storage
- 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)
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
)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.
Press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
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.
Neurodesk is ready to use! Click “What’s next?” on the left of this page for further instructions.
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…")
Note
Notice that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.Click on the terminal from which you ran neurodesktop
Press Ctrl-C
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 provider | link |
---|---|
Oracle | https://mri.sbollmann.net/index.php/2020/12/08/run-neurodesk-on-oracle-cloud-free-tier/ |
Azure | https://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-20220329 vnmd/neurodesktop:20220329
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-20220329 vnmd/neurodesktop:20220329 --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-20220329 vnmd/neurodesktop:20220329 --vnc --rdp
VNC allows for multiple desktop connections to same instance
Note: Neurodesktop VNC on the browser currently does not support auto-resolution
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-20220329 vnmd/neurodesktop:20220329 --vnc
Open a VNC Client and connect to port 5901
8 - Play
Click the link below 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).