Getting Started

• 1: Neurodesktop
• 1.1: Neurodesk App
• 1.2: Linux
• 1.3: MacOS
• 1.4: Windows
• 1.5: Play
• 1.6: Nectar Virtual Desktop Service
• 1.7: Cloud
• 1.8: Data Storage
• 2: Neurocommand
• 2.1: Linux
• 2.2: Windows
• 2.3: HPC
• 2.4: Visual Studio Code
• 3: Neurocontainers
• 3.1: CVMFS
• 3.2: DataLad
• 3.3: Docker
• 3.4: Google Colab
• 3.5: Singularity
• 3.6: Windows 11 and Windows Subsystem for Linux

1 - Neurodesktop

Video tutorial

See below for a 4 minute tutorial on Installation, Usage and Data Access with Neurodesktop

1.1 - Neurodesk App

Minimum System Requirements

1. At least 5GB free space for neurodesktop base image
2. Docker requirements.

Installing Docker

The Neurodesk App requires Docker to be installed on your computer. If you already have Docker installed, you can skip this step.

• Docker Desktop for Windows
• Docker Desktop for Mac
• Docker Engine for Linux

After installation, open a terminal (Linux/macOS) or command prompt (Windows) and run the following command to verify that Docker is working correctly:

docker --version
docker run hello-world

Downloading Neurodesk App

• Debian, Ubuntu Linux Installer
• Red Hat, Fedora, SUSE Linux Installer
• Arch-based package via AUR
• macOS Intel Installer, macOS Apple silicon Installer
• Windows Installer

Installing Neurodesk App

If you have an existing Neurodesk App installation, please first uninstall it by following the uninstall instructions here. Then, install the app for your system:

• Debian, Ubuntu Linux Installer: sudo apt install -f ./NeurodeskApp-Setup-Debian.deb
• Red Hat, Fedora, SUSE Linux Installer: sudo rpm -i NeurodeskApp-Setup-Fedora.rpm
• Arch-based package via AUR: yay neurodesk (or follow instructions here)
• macOS Installer: Double click the downloaded dmg file, then drag the NeurodeskApp.app to the Applications folder; for starting the app: Right click on the NeurodeskApp.app and select “Open”. For Apple Silicon systems (M1/M2): Make sure to enable Rosetta support in the docker settings for best performance!
• Windows Installer: Double click the downloaded exe file; Accept to install from an unknown publisher with Yes; then accept the license agreement and click finish at the end.

Launching Neurodesk App

The Neurodesk App can be launched directly from your operating system’s application menu, or by running the neurodeskapp command in the command line.

Note that the Neurodesk App will set the File Browser’s root directory based on the launch method used. The default working directory is the user’s home directory - this can be customized from the Settings dialog.

Sessions and Projects

Sessions represent local project launches and connections to existing Neurodesk servers. Each Neurodesk UI window in the app is associated with a separate session and sessions can be restored with the same configuration later on.

Session start options

You can start a new session by using the links at the Start section of the Welcome Page.

• Open Local Neurodesk.. creates a new session in the default working directory.
• Connect to remote Neurodesk server.. creates a session by connecting to a remote Neurodesk server.

Previously opened sessions are stored as part of application data and they are listed on the Welcome Page. Clicking an item in the Recent sessions list restores the selected session.

Connecting to local Neurodesk

Neurodesk App creates new Neurodesk sessions by launching a locally running Neurodesk server and connecting to it. To open a local instance, click the Open Local Neurodesk.. button in the Start section of the Welcome Page.

This will show a Jupyterlab interface. There are two options to interact with Neurodesk through this interface:

• By clicking the NeurodeskApp icon on the right. This will launch a new window to start a Neurodesk interface.
• By module loading containers on the left bar. You can interact with loaded modules through the command line interface.

Connecting to a remote Neurodesk Server

It can also connect to an existing Neurodesk server instance that is running remotely. In order to connect to a server, click the Connect to remote Neurodesk server.. button in the Start section of the Welcome Page.

This will launch a dialog that automatically lists the remote Neurodesk server instances.

Select a server from the list or enter the URL of the Neurodesk application server. If the server requires a token for authentication, make sure to include it as a query parameter of the URL as well (/lab?token=<token-value>). After entering a URL hit Enter key to connect.

If the Persist session data option is checked, then the session information is stored and Neurodesk App will re-use this data on the next launch. If this option is not checked, the session data is automatically deleted at the next launch and servers requiring authentication will prompt for re-login.

You can delete the stored session data manually at any time by using the Clear History option in the Privacy tab of Settings dialog.

Configuration and data files

Neurodesk App stores data in ~/neurodesktop-storage for Linux and Mac, or C:/neurodesktop-storage for Windows, as default.

Add a Custom Data Directory

Neurodesk App stores its data in the following locations:

• By default, /home/jovyan/neurodesktop-storage in the app (which is bound with local directory ~/neurodesktop-storage in Unix or C:/neurodesktop-storage in Windows)

• By choice, in the settings window below, select Additional Directory on the left side bar, click Change button to select the local directory, then click Apply & restart. The next time you start the app, the data from the local directory can be found in /home/jovyan/data.

Uninstalling Neurodesk App

Debian, Ubuntu Linux

sudo apt-get purge neurodeskapp # remove application
sudo rm /usr/bin/neurodeskapp # remove command symlink
rm -rf ~/.config/neurodeskapp # to remove application cache

Red Hat, Fedora, SUSE Linux

sudo rpm -e neurodeskapp # remove application
sudo rm /usr/bin/neurodeskapp # remove command symlink
rm -rf ~/.config/neurodeskapp # to remove application cache

Arch-based Linux distributions

sudo pacman -Rs neurodeskapp-bin

macOS

Find the application installation NeurodeskApp.app in Finder (in /Applications or ~/Applications) and move to Trash by using CMD + Delete. Clean other application generated files using:

rm -rf ~/Library/neurodeskapp # to remove application cache
rm -rf ~/Library/Application\ Support/neurodeskapp # to remove user data

Windows

On Windows, go to Windows Apps & Features dialog using Start Menu -> Settings -> Apps and uninstall Neurodesk App as shown below.

In order to remove application cache, delete C:\Users\<username>\AppData\Roaming\neurodeskapp directory.

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

0. Install Docker or Podman

Install Docker from here: https://docs.docker.com/get-docker/. Additional information is available below. Alternatively, Neurodesk also works with Podman (https://podman.io/).

To set up Neurodesk on Ubuntu, ensure both Podman client and server are installed. Follow the Podman installation instructions provided at https://podman.io/docs/installation for server setup.

sudo apt update && sudo apt upgrade -y
sudo apt install curl
echo "deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_20.04/ /" | sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:stable.list
curl -L "https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_20.04/Release.key" | sudo apt-key add -
sudo apt update
sudo apt-get -y install podman

For the client setup, execute the following commands.

systemctl --user --now enable podman.socket
sudo loginctl enable-linger $USER
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
cat  ~/.ssh/id_ed25519.pub | cat >> ~/.ssh/authorized_keys
podman system connection add development --identity ~/.ssh/id_ed25519 ssh://$USER@$HOSTNAME/run/user/$UID/podman/podman.sock

1. Optional: only for ARM64 hardware

Neurodesk supports ARM64 hardware through binfmt

To enable Neurodesk on ARM64 hardware run this setup step:

sudo docker run --privileged --rm tonistiigi/binfmt --install all

2. Run Neurodesktop

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

Then use one of the following options to run Neurodesktop:

Option 1 (Recommended for local installations): Neurodesk-App

Instructions on installing and using the app: https://www.neurodesk.org/docs/getting-started/neurodesktop/neurodeskapp/

Option 2 (Advanced and for remote installations): Using Terminal

0. If the Linux machine is remote (e.g. in the cloud), connect to the machine with a port forwarding first:

ssh -L 8888:127.0.0.1:8888 USER@IP

1. then start neurodesktop:

1.a) with a persistent home directory:

docker volume create neurodesk-home &&
sudo docker run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  --mount source=neurodesk-home,target=/home/jovyan \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

1.b) without a persistent home directory:

sudo docker run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

chmod a+rwx ~/neurodesktop-storage

2. Once neurodesktop is downloaded, leave the terminal open and check which server neurodesktop is running on (Avoid pressing CTRL+C).

3. To access neurodesktop, open your web browser and type in one of the provided URLs in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).

"http://127.0.0.1:8888 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 have used Neurodesktop, wait until the desktop appears (it may take a few seconds). Otherwise, it should appear instantaneously.

6. Neurodesk is now ready to use! See the tutorials page for advice on how to use Neurodesk.

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 ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

GPU support

RHEL/CentOS (yum-based)

sudo yum install nvidia-container-toolkit -y

Ubuntu/Debian (apt-based)

sudo apt install nvidia-container-toolkit -y

Running neurodesktop container with GPU

sudo docker run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  --gpus all \
  -p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 \
  vnmd/neurodesktop:2024-03-27

Running tensorflow (w/ GPU)

Using tensorflow (python)

mamba 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 --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 -p 3390:3389 \
  -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

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 --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27 --vnc

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

sudo docker run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27 --vnc --rdp

Using a VNC Client

Startup Neurodesktop using the following command:

sudo docker run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 -p 5901:5901 \
  -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27 --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.

1.3 - MacOS

Quickstart

1. Install Docker or Podman

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

Alternatively, Neurodesk also works with Podman, follow the Podman installation instructions provided at https://podman.io/docs/installation.

2. Run Neurodesktop

Use one of the following options to run Neurodesktop:

Option 1 (Recommended): Neurodesk-App

Instructions on installing and using the app: https://www.neurodesk.org/docs/getting-started/neurodesktop/neurodeskapp/

Option 2 (Advanced): Using Terminal

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

1. Open a terminal, and type the following command to automatically download the neurodesktop container and run it

1.a) with a persistent home directory:

docker volume create neurodesk-home &&
docker run \
--shm-size=1gb -it --privileged --user=root --name neurodesktop \
-v ~/neurodesktop-storage:/neurodesktop-storage \
--mount source=neurodesk-home,target=/home/jovyan \
-e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
-p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

1.b) without a persistent home directory:

docker run \
--shm-size=1gb -it --privileged --user=root --name neurodesktop \
-v ~/neurodesktop-storage:/neurodesktop-storage \
-e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
-p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

If you get errors in neurodesktop then check if the ~/neurodesktop-storage directory is writable for all users. If it is not, run chmod a+rwx ~/neurodesktop-storage

2. Once neurodesktop is downloaded, leave the terminal open and check which server neurodesktop running on (Avoid pressing CTRL+C).

3. To access neurodesktop, open your web browser and navigate to one of the URLs shown in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).

3. If prompted, press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”

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

5. Neurodesk is ready to use! See the tutorials page for advice on how to use Neurodesk.

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 --user=root --name neurodesktop \
-v ~/neurodesktop-storage:/neurodesktop-storage \
-p 3390:3389 -p 8888:8888 \
-e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

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 --user=root --name neurodesktop \
-v ~/neurodesktop-storage:/neurodesktop-storage \
-e VNC_ENABLE=true -p 8888:8888 \
-e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

Using a VNC Client

Startup Neurodesktop using the following command:

docker run \
--shm-size=1gb -it --privileged --user=root --name neurodesktop \
-v ~/neurodesktop-storage:/neurodesktop-storage \
-e VNC_ENABLE=true -p 5901:5901 -p 8888:8888 \
-e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

Open a VNC Client and connect to port 5901

1.4 - 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, minimum 20GB space recommended for WSL with Ubuntu

Quickstart

1. Install Docker or Podman

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

Alternatively, Neurodesk also works with Podman, follow the Podman installation instructions provided at https://podman.io/docs/installation.

2. Run Neurodesktop

Use one of the following options to run Neurodesktop:

Option 1 (Recommended): Neurodesk-App

Instructions for installing and using the app: https://www.neurodesk.org/docs/getting-started/neurodesktop/neurodeskapp/

Option 2 (Advanced): Using Terminal

1. Open a terminal (e.g. Powershell), and type the following command to automatically download the neurodesktop container and run it

1.a) with a persistent home directory:

docker volume create neurodesk-home

docker run --shm-size=1gb -it --privileged --user=root --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage --mount source=neurodesk-home,target=/home/jovyan -p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

1.b) without a persistent home directory:

docker run --shm-size=1gb -it --privileged --user=root --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

2. Once neurodesktop is downloaded, leave the terminal open and check which server neurodesktop running on (Avoid pressing CTRL+C). ]

3. To access neurodesktop, open your web browser and type in one of the URLs provided in your terminal (e.g. http://127.0.0.1:8888/lab?token=your_unique_token).

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

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

6. Neurodesk is ready to use! See the tutorials page for advice on how to use Neurodesk.

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 Remote Desktop Protocol (RDP) Client

Startup Neurodesktop using the following command:

docker run \
--shm-size=1gb -it --privileged --user=root --name neurodesktop \
-v C:/neurodesktop-storage:/neurodesktop-storage \
-p 3390:3389 -p 8888:8888 \
-e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

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 --user=root --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27 --vnc 

Using a Virtual Network Computing (VNC) Client

Startup Neurodesktop using the following command:

docker run --shm-size=1gb -it --privileged --user=root --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -p 5901:5901 -p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27 --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.

1.5 - Play

Neurodesk Play

• Recommended if you want to quickly try out Neurodesktop without installing docker or signing in
• No login or sign-up required
• Does NOT preserve files from previous sessions

To use Neurodesk Play, choose the link below closest to your location:

• Australia
• US
• Europe

How to transfer data onto Neurodesk Play

We provide different ways from drag-and-drop, to cloud storage to transfer your files in and out of Neurodesk Play.

1.6 - Nectar Virtual Desktop Service

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

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

Instructions for use

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

2. Click on “Sign in”.

3. Choose the AAF option.

4. Choose your institution from the list.

5. Provide your email address and password.

6. Click on create a Workspace (you only need to do this when you sign in for the first time).

7. Fill form ‘Apply for new Workspace’ and submit.

8. Click on “EXPLORE”.

9. Click “VIEW DETAILS” under Neurodesktop:

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

11. Choose the desired availability zone.

12. Wait until everything is completed:

13. Click “OPEN DESKTOP ->”:

14. For a general guide on using the ARDC virtual desktops, click here: https://tutorials.rc.nectar.org.au/virtual-desktop-service/01-overview

15. For a specific explanation on how to launch the various applications available in the Neurodesktop desktop, follow the instructions here: https://www.neurodesk.org/docs/getting-started/neurodesktop/

1.7 - Cloud

Options for Running Neurodesk on cloud computing resources

There are a couple of ways how Neurodesktop can be run on cloud computing resources:

1. The first and easiest option is to provision a virtual Linux machine and run docker on this machine similar to a local Linux setup: https://www.neurodesk.org/docs/getting-started/neurodesktop/linux/
2. Another option is to use Windows VMs and some groups have had success with that. Here is a detailed instructions on this setup: https://github.com/NeuroDesk/neurodesk.github.io/blob/main/static/docs/getting-started/neurodesktop/Neurodesk_Windows_Technion.pdf
3. The third and most scalable solution is to run Neurodesk via Kubernetes. This setup is a bit more complex, but can handle many simultaneous users and is ideal for research groups and workshops. The easiest way to deploy Neurodesk on Kubernetes is to use Zero to Jupyterhub (https://z2jh.jupyter.org/en/stable/) - then you can use the Neurodesk image like any other jupyterhub image. If you do not want to run a privileged container you need to deploy the cvmfs setup on Kubernetes as well (https://github.com/cvmfs-contrib/cvmfs-csi).

1.8 - Data Storage

Drag and Drop

Uploading files

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

Downloading files

To download files from the desktop using the same mechanism you will 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”:

a click (or double click 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).

Note that it is only possible to upload or download one file at a time through this interface. If you have multiple files in a directory we recommend zipping the directory and then transferring one zip archive:

zip files.zip files/

Local storage

If you are running Neurodesktop on your own hardware there will be a direct connection between the “Storage” folder on the Desktop, which is a link between “/neurodesktop-storage” in neurodesktop and the “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. Important: the mountpoint inside neurodesktop needs to be named /data, otherwise the applications will not see the files without modifying the SINGULARITY_BINDPATH variable in your .bashrc.

If you are using the NeurodeskApp, you can set an additional storage location through the settings

If you are starting Neurodesk through the command line, here is an example for Windows adding another storage directory:

docker run --shm-size=1gb -it --privileged --user=root --name neurodesktop -v C:/neurodesktop-storage:/neurodesktop-storage -v D:/moredata:/data -p 8888:8888 -e NEURODESKTOP_VERSION=2024-03-27 vnmd/neurodesktop:2024-03-27

Note for Windows users: Connecting network shares from Windows to Neurodesk can cause problems, so be careful when attempting this. Also, be aware that processing large amounts of files stored on a Windows filesystem inside Neurodesk will come with a performance penality due to the file system translation in the background. One option to get around these problems is to directly accessing your storage infrastructure inside Neurodesk.

Cloud storage

Another way to get your data into Neurodesktop is to use a cloud storage provider like Dropbox, OneDrive, OwnCloud, Nextcloud or more general 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.

Mounting webdav storage using davfs2

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

sudo mount -t davfs https://yourOwnCloudInstance.com/plus/remote.php/webdav/ /data/

It then asks you for a username and password, which you can generate in the settings: yourOwnCloudInstance/plus/settings/personal?sectionid=security

Rclone

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

• start the configuration in a terminal window rclone config
• Create a new remote: n
• Provide a name for the remote: OwnCloud
• For the “Storage” option choose: webdav
• As “url” set: https://yourOwnCloudInstance.com/plus/remote.php/webdav/
• As “vendor” set OwnCloud: 2
• Set your OwnCloud username after generating an access token yourOwnCloudInstance/plus/settings/personal?sectionid=security
• Choose to type in your own password: y
• Enter the Password / Token from the OwnCloud 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 OwnCloud:/raw-data-for-science-paper .
• or upload data to OwnCloud: rclone copy --progress --transfers 8 . OwnCloud:/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 the following commands in the Neurodesktop environment:

ml globus
# First run the setup:
globusconnectpersonal -setup

#Follow the instructions in the terminal: 
#1) copy the URL into a browser and generate the Native App Authorization Code
#2) then copy this code and paste it in the terminal
#3) then name the endpoint, e.g. Neurodesktop

# Then start the GUI:
globusconnectpersonal -gui

# If the connection fails, reset the permissions on the key file:
chmod 600 /home/jovyan/.globusonline/lta/relay-anonymous-key.pem

# If the connection still fails, start the client like this to get more information
globusconnectpersonal -debug

Then add the directories you want to share with globus, by opening File -> Preferences:

and then add the paths required and hit Save:

Then you can go to the globus file-manager https://app.globus.org/file-manager and your neurodesktop instance will be an endpoint for globus. You can change the path to any location you specified in the Preferences:

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

2 - Neurocommand

Neurocommand requires a Linux host machine, virtual machine or WSL for Windows.

2.1 - Linux

Ways of using Neurocommand in Linux:

1. You can use the module files for Neurocontainers directly via CVMFS: https://www.neurodesk.org/docs/getting-started/neurocontainers/cvmfs/
2. or you can install Neurocommand as described here:

Requirements:

Required

• python 3.6+ https://docs.conda.io/en/latest/miniconda.html#linux-installers
• singularity https://docs.sylabs.io/guides/3.5/user-guide/quick_start.html
• git
• lmod https://lmod.readthedocs.io/en/latest/

command line mode (e.g. running on an HPC or CVL)

• Load singularity and for best performance it should be 3.x e.g. module load singularity/3.5.0
• Load or install aria2 to optimize the download performance of our containers e.g. module load aria2c
• Run git clone https://github.com/NeuroDesk/neurocommand.git to clone the repository - make sure to clone this to a directory with enough storage, write permissions and NOT a symbolic link (to be sure run cd `pwd -P`)!
• Run cd neurocommand to change into the directory
• Run pip3 install -r neurodesk/requirements.txt --user to install pre-requisite python packages
• Run bash build.sh --cli to install in cli mode
• Run bash containers.sh for installing individual containers or bash containers.sh --all for installing all containers
• Run module use $PWD/local/containers/modules/ to add the containers to your module search path. Add this to your .bashrc if working. When adding to your .bashrc you will need to replace $PWD to point to the correct path, i.e. module use ~/neurocommand/local/containers/modules/.
• Run ml avail to see the installed containers at the top of the list (neurodesk containers will take preference over system modules with the same name). - If a container is not yet there run ml --ignore_cache avail
• Every time you start a new shell you need to run module use PathToYourContainers or add this command to you .bashrc file.

GPU support

Some of our containers contain GPU-accelerated applications. Here is an example that runs the GPU accelerated program eddy in FSL:

module load fsl/6.0.5.1
export neurodesk_singularity_opts='--nv'
eddy_cuda9.1

For Lxde desktops

If running on an lxde desktop… Run bash build.sh --lxde --edit

For Mate desktops

Run bash build.sh --init (or bash build.sh --lxde --edit)
lxde/mate: Mate
installdir: Where all the neurocommand files will be stored (Default: ./local)
appmenu: The linux menu xml file. (Usually /etc/xdg/menus/****-applications.menu)
appdir: Location for the .desktop files for this linux desktop (Usually /usr/share/applications)
deskdir: Location for the .directory files for this linux desktop (Typically /usr/share/desktop-directories)

For desktop menus:

sudo bash install.sh to install
Creates symlinks to menu files in installation dir

sudo bash uninstall.sh to uninstall
Removes symlinks

For user-specific desktop menus in a shared Linux environment

mkdir -p $HOME/.config/menus
mkdir -p $HOME/.local/share/applications
mkdir -p $HOME/.local/share/desktop-directories
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/xfce-applications.menu $HOME/.config/menus
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/neurodesk-applications.menu $HOME/.config/menus
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/applications $HOME/.local/share/applications/neurodesk
ln -sfn /PATH_TO_YOUR_INSTALLATION/neurocommand/local/desktop-directories $HOME/.local/share/desktop-directories/neurodesk

To update

Run git pull
Run bash build.sh # this updates the neurocommand but not the modules install.sh does not need to be run again to update containers go into the neurodesktop directory and run bash containers.sh Choose the module you want to update for example you want to update mrtrix3/3.0.2 module with the eddy_cuda fix: ~/neurocommand/local/fetch_containers.sh mrtrix3 3.0.2 20221108 mrview $@

To download all containers

Run bash containers.sh --all

2.2 - Windows

WSL (w/ Ubuntu + LXDE)

For more information on WSL: https://docs.microsoft.com/en-us/windows/wsl

Setting up

1. Setup WSL2 using the following instructions (Ubuntu 18.04 recommended)
   https://docs.microsoft.com/en-us/windows/wsl/install-win10 Proceed until a Ubuntu bash shell is available from the Windows Host
   Run the remaining commands in the Bash shell
2. sudo apt-get install lxde to install LXDE desktop in WSL
3. Reboot
4. sudo apt-get install xrdp to install XRDP in WSL
5. Open /etc/xrdp/xrdp.ini Change port=3389 to port=3390 and save
6. Run echo startlxde > ~/.xsession

Running

1. sudo service xrdp start to start xrdp server
2. Open Microsoft Remote Desktop Connection in Windows host
3. Connect to localhost:3390
4. In the next login page, leave Session as Xorg. Enter your WSL username and password and click OK
5. This should open an LXDE Linux Desktop environment. Follow Linux guide from here on

2.3 - HPC

Ways of using Neurocommand in Linux:

1. You can use Neurocontainers (i.e., download Singularity containers) directly via CVMFS: https://www.neurodesk.org/docs/getting-started/neurocontainers/cvmfs/
2. or you can install Neurocommand as described here:

Requirements:

Required for installation

• python 3.6+ https://docs.conda.io/en/latest/miniconda.html#linux-installers
• singularity https://docs.sylabs.io/guides/3.5/user-guide/quick_start.html
• git

Required for use

• singularity https://docs.sylabs.io/guides/3.5/user-guide/quick_start.html

Optional, but recommended

• lmod https://lmod.readthedocs.io/en/latest/

NB: Your HPC will likely have lmod and Singularity already installed - check with your sysadmin

Command line mode (e.g. running on an HPC or CVL)

• Load singularity and for best performance, it should be 3.x e.g.

module load singularity/3.5.0
# Note: Some HPCs install singularity/apptainer on the compute nodes directly (e.g. Bunya at UQ), so you don't need to do this step then.

• Load or install aria2 to optimize the download performance of our containers (THIS IS OPTIONAL)

module load aria2c

• To install the repository, run the following (make sure to clone this to a directory with enough storage, write permissions and NOT a symbolic link (to be sure run cd `pwd -P`)!). It is recommended to perform this setup in a Python venv or conda environment:

git clone https://github.com/NeuroDesk/neurocommand.git 
cd neurocommand 
pip3 install -r neurodesk/requirements.txt --user 
bash build.sh --cli
bash containers.sh
export SINGULARITY_BINDPATH=$PWD
# OR
export APPTAINER_BINDPATH=$PWD

Install Containers

• If these steps are successful, the help will be displayed
• Install all or only specific containers by following the instructions, e.g.:

To search for containers that have “itksnap” in the name:

bash containers.sh itksnap

Then you can copy and paste the specific install command or you can install all containers with that name:

bash containers.sh --itksnap

To download all containers (be careful - there are a lot of containers!):

bash containers.sh --all

Adding your containers to lmod

• To add each container to the module search path, run the following:

module use $PWD/local/containers/modules/

• It may be a good idea to add this to your .bashrc if it works. When adding to your .bashrc you will need to replace $PWD to point to the correct path, i.e.

module use ~/neurocommand/local/containers/modules/

• It is very important to also set the SINGULARITY_BINDPATH or the APPTAINER_BINDPATH variable in your .bashrc. This variable must contain a comma-separated list of directories you want to access with the Neurodesk tools.

e.g.:

export SINGULARITY_BINDPATH=/scratch/,/data/
export APPTAINER_BINDPATH=/scratch/,/data/
#Note: User the correct line depending on your installation. Do not add a directory that does not exist, otherwise the containers will not start!

• to see the installed containers at the top of the list (neurodesk containers will take preference over system modules with the same name), run:

module --ignore_cache avail

Starting a new shell

• Every time you start a new shell you will need to run conda activate neurocommand. Unless you added it to your .bashrc, you will also need to run module use PathToYourContainers.

To update

Run

git pull
bash build.sh --cli

• this updates the neurocommand but not the modules
• install.sh does not need to be run again to update containers go into the neurodesktop directory and run

bash containers.sh

Choose the module you want to update for example you want to update mrtrix3/3.0.2 module with the eddy_cuda fix:

~/neurocommand/local/fetch_containers.sh mrtrix3 3.0.2 20221108 mrview $@

or run this to update all containers

bash containers.sh --all

Example clusters

UQ Bunya

Neurodesk is already installed at UQ’s Bunya supercomputer. To access neurodesk tools you need to be in an interactive job (so either start a virtual desktop via Open On-Demand: https://bunya-ondemand.rcc.uq.edu.au/pun/sys/dashboard) or run:

salloc --nodes=1 --ntasks-per-node=1 --cpus-per-task=1 --mem=5G --job-name=TinyInteractive --time=01:00:00 --partition=debug --account=REPLACE_THIS_WITH_YOUR_AccountString srun --export=PATH,TERM,HOME,LANG --pty /bin/bash -l

Then load the neurodesk modules:

module use /sw/local/rocky8/noarch/neuro/software/neurocommand/local/containers/modules/
export APPTAINER_BINDPATH=/scratch,/QRISdata

Now you can list all modules (Neurodesk modules are the first ones in the list):

ml av

Or you can module load any tool you need:

ml qsmxt/6.4.1

2.4 - Visual Studio Code

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

Please see additional instructions below if 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 - WSL (For windows hosts)

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.

This may take about a minute if it is the first time you are connecting, as VS code has to install the VS Code server onto the container. Repeat connections should be faster.

First time connection

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

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

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

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

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

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

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

3 - Neurocontainers

3.1 - CVMFS

Install the CernVM File System (CVMFS)

To begin, install CVMFS. Follow the official instructions here: https://cvmfs.readthedocs.io/en/stable/cpt-quickstart.html#getting-the-software

An example installation for Ubuntu in Windows Subsystem for Linux (WSL) would look like this:

sudo apt-get install lsb-release
wget https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest_all.deb
sudo dpkg -i cvmfs-release-latest_all.deb
rm -f cvmfs-release-latest_all.deb
sudo apt-get update
sudo apt-get install build-essential
sudo apt-get install cvmfs

Configure CVMFS

Once installed create the keys and configure the servers used:

sudo mkdir -p /etc/cvmfs/keys/ardc.edu.au/


echo "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwUPEmxDp217SAtZxaBep
Bi2TQcLoh5AJ//HSIz68ypjOGFjwExGlHb95Frhu1SpcH5OASbV+jJ60oEBLi3sD
qA6rGYt9kVi90lWvEjQnhBkPb0uWcp1gNqQAUocybCzHvoiG3fUzAe259CrK09qR
pX8sZhgK3eHlfx4ycyMiIQeg66AHlgVCJ2fKa6fl1vnh6adJEPULmn6vZnevvUke
I6U1VcYTKm5dPMrOlY/fGimKlyWvivzVv1laa5TAR2Dt4CfdQncOz+rkXmWjLjkD
87WMiTgtKybsmMLb2yCGSgLSArlSWhbMA0MaZSzAwE9PJKCCMvTANo5644zc8jBe
NQIDAQAB
-----END PUBLIC KEY-----" | sudo tee /etc/cvmfs/keys/ardc.edu.au/neurodesk.ardc.edu.au.pub

echo "CVMFS_USE_GEOAPI=yes" | sudo tee /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf

echo 'CVMFS_SERVER_URL="http://cvmfs1.neurodesk.org/cvmfs/@fqrn@;http://cvmfs2.neurodesk.org/cvmfs/@fqrn@;http://cvmfs3.neurodesk.org/cvmfs/@fqrn@"' | sudo tee -a /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf 

echo 'CVMFS_KEYS_DIR="/etc/cvmfs/keys/ardc.edu.au/"' | sudo tee -a /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf

echo "CVMFS_HTTP_PROXY=DIRECT" | sudo tee  /etc/cvmfs/default.local
echo "CVMFS_QUOTA_LIMIT=5000" | sudo tee -a  /etc/cvmfs/default.local

sudo cvmfs_config setup

For WSL users

You will need to run this for each new WSL session:

sudo cvmfs_config wsl2_start

Test if the connection works:

sudo cvmfs_config chksetup

ls /cvmfs/neurodesk.ardc.edu.au

sudo cvmfs_talk -i neurodesk.ardc.edu.au host probe
sudo cvmfs_talk -i neurodesk.ardc.edu.au host info

cvmfs_config stat -v neurodesk.ardc.edu.au

For Ubuntu 22.04 users

If configuring CVMFS returns the following error:

Error: failed to load cvmfs library, tried: './libcvmfs_fuse3_stub.so' '/usr/lib/libcvmfs_fuse3_stub.so' '/usr/lib64/libcvmfs_fuse3_stub.so' './libcvmfs_fuse_stub.so' '/usr/lib/libcvmfs_fuse_stub.so' '/usr/lib64/libcvmfs_fuse_stub.so'
./libcvmfs_fuse3_stub.so: cannot open shared object file: No such file or directory
/usr/lib/libcvmfs_fuse3_stub.so: cannot open shared object file: No such file or directory
/usr/lib64/libcvmfs_fuse3_stub.so: cannot open shared object file: No such file or directory
./libcvmfs_fuse_stub.so: cannot open shared object file: No such file or directory
libcrypto.so.1.1: cannot open shared object file: No such file or directory
/usr/lib64/libcvmfs_fuse_stub.so: cannot open shared object file: No such file or directory


Failed to read CernVM-FS configuration

A temporary workaround is:

wget https://mirror.umd.edu/ubuntu/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.15_amd64.deb
dpkg -i libssl1.1_1.1.1f-1ubuntu2.15_amd64.deb

Install singularity/apptainer

e.g for Ubuntu/Debian install apptainer:

sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt-get update
sudo apt-get install -y apptainer 

e.g. for Ubuntu/Debian install singularity:

export VERSION=1.18.3 OS=linux ARCH=amd64 && \
    wget https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz && \
    sudo tar -C /usr/local -xzvf go$VERSION.$OS-$ARCH.tar.gz && \
    rm go$VERSION.$OS-$ARCH.tar.gz

echo 'export GOPATH=${HOME}/go' >> ~/.bashrc && \
    echo 'export PATH=/usr/local/go/bin:${PATH}:${GOPATH}/bin' >> ~/.bashrc && \
    source ~/.bashrc

go get -d github.com/sylabs/singularity

export VERSION=v3.10.0 # or another tag or branch if you like && \
    cd $GOPATH/src/github.com/sylabs/singularity && \
    git fetch && \
    git checkout $VERSION # omit this command to install the latest bleeding edge code from master

export VERSION=3.10.0 && # adjust this as necessary \
    mkdir -p $GOPATH/src/github.com/sylabs && \
    cd $GOPATH/src/github.com/sylabs && \
    wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-ce-${VERSION}.tar.gz && \
    tar -xzf singularity-ce-${VERSION}.tar.gz && \789
    cd ./singularity-ce-${VERSION} && \
    ./mconfig --without-seccomp --without-conmon

./mconfig --without-seccomp --without-conmon && \
    make -C ./builddir && \
    sudo make -C ./builddir install

export PATH="/usr/local/singularity/bin:${PATH}"

Use of Neurodesk CVMFS containers

The containers are now available in /cvmfs/neurodesk.ardc.edu.au/containers/ and can be started with:

singularity shell /cvmfs/neurodesk.ardc.edu.au/containers/itksnap_3.8.0_20201208/itksnap_3.8.0_20201208.simg

make sure that SINGULARITY_BINDPATH includes the directories you want to work with:

export SINGULARITY_BINDPATH='/cvmfs,/mnt,/home'

For WSL users

The homedirectory might not be supported. Avoid mounting it with

singularity shell --no-home /cvmfs/neurodesk.ardc.edu.au/containers/itksnap_3.8.0_20201208/itksnap_3.8.0_20201208.simg

or configure permanently:

sudo vi /etc/singularity/singularity.conf

set

mount home = no

Install module system

sudo yum install lmod

or

sudo apt install lmod

Use of containers in the module system

Configuration for module system

Create a the new file /usr/share/module.sh with the content (NOTE: update the version, here 6.6, with your lmod version, e.g. 8.6.19):

# system-wide profile.modules                                          #
# Initialize modules for all sh-derivative shells                      #
#----------------------------------------------------------------------#
trap "" 1 2 3

case "$0" in
    -bash|bash|*/bash) . /usr/share/lmod/6.6/init/bash ;;
       -ksh|ksh|*/ksh) . /usr/share/lmod/6.6/init/ksh ;;
       -zsh|zsh|*/zsh) . /usr/share/lmod/6.6/init/zsh ;;
          -sh|sh|*/sh) . /usr/share/lmod/6.6/init/sh ;;
                    *) . /usr/share/lmod/6.6/init/sh ;;  # default for scripts
esac

trap - 1 2 3

Make the module system usable in the shell

Add the following lines to your ~/.bashrc file:

if [ -f '/usr/share/module.sh' ]; then source /usr/share/module.sh; fi

if [ -d /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules ]; then
        # export MODULEPATH="/cvmfs/neurodesk.ardc.edu.au/neurodesk-modules"
        module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*
else
        export MODULEPATH="/neurodesktop-storage/containers/modules"              
        module use $MODULEPATH
        export CVMFS_DISABLE=true
fi

if [ -f '/usr/share/module.sh' ]; then
        echo 'Run "ml av" to see which tools are available - use "ml <tool>" to use them in this shell.'
        if [ -v "$CVMFS_DISABLE" ]; then
                if [ ! -d $MODULEPATH ]; then
                        echo 'Neurodesk tools not yet downloaded. Choose tools to install from the Application menu.'
                fi
        fi
fi

Restart the current shell or run

source ~/.bashrc

Use of containers in the module system

export SINGULARITY_BINDPATH='/cvmfs,/mnt,/home'
module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*
ml fsl
fslmaths

3.2 - DataLad

install datalad, datalad-containers, and ReproNim containers repo

conda install datalad
pip install datalad_container
datalad install https://github.com/ReproNim/containers.git
cd containers

get a list of all available default containers

datalad containers-list

download and run the latest container version

datalad containers-run -n neurodesk-romeo

Change version of container

Option 1: change version in .datalad/config

vi .datalad/config
# now change the version of the container you like
# all available containers can be seen via `ls images/neurodesk`
datalad save -m 'downgraded version of romeo to x.x.x'
datalad containers-run -n neurodesk-romeo

Option 2: change version using freeze_versions script

# all available containers can be seen via `ls images/neurodesk`
scripts/freeze_versions neurodesk-romeo=3.2.4
datalad save -m 'downgraded version of romeo to 3.2.4'
datalad containers-run -n neurodesk-romeo

3.3 - Docker

Our containers are automatically built in https://github.com/NeuroDesk/neurocontainers/ and hosted on dockerhub and on github

Pull Docker containers

e.g. for a julia container docker

docker pull vnmd/julia_1.6.1

You an also build singularity images from dockerhub

singularity build julia_1.6.1.simg docker://vnmd/julia_1.6.1

Replace julia_1.6.1 with your selected application. You can find the available containers here: https://www.neurodesk.org/applications/

3.4 - Google Colab

Open a notebook in Google Colab and run the following commands to set up the Neurodesk environment:

import os
os.environ["LD_PRELOAD"] = "";
os.environ["APPTAINER_BINDPATH"] = "/content"
os.environ["MPLCONFIGDIR"] = "/content/matplotlib-mpldir"
os.environ["LMOD_CMD"] = "/usr/share/lmod/lmod/libexec/lmod"

!curl -J -O https://raw.githubusercontent.com/NeuroDesk/neurocommand/main/googlecolab_setup.sh
!chmod +x googlecolab_setup.sh
!./googlecolab_setup.sh

os.environ["MODULEPATH"] = ':'.join(map(str, list(map(lambda x: os.path.join(os.path.abspath('/cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/'), x),os.listdir('/cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/')))))

Once this setup is completed you can list the available Neurodesk applications like this:

import lmod
await lmod.avail()

and use applications like this:

await lmod.load('fsl/6.0.4')
!bet

This notebook demonstrates how to use all Neurodesk applications in Google Colab: https://colab.research.google.com/drive/1g5cnZxj1llRaHmOs4xSglqsXnFkQYuol?usp=sharing

This is a google colab notebook that shows how to integrate with google drive and contains an example how to run fMRIprep in google colab: https://colab.research.google.com/drive/11wVBkjNvrzo2TkUAILtWnPumAeFAfqkl?usp=sharing

and more examples can be found here: https://github.com/NeuroDesk/example-notebooks/

3.5 - Singularity

Our docker containers are converted to singularity containers and stored on Object storage.

Download Singularity Containers

First get an overview of which containers are available as Singularity containers: https://github.com/NeuroDesk/neurocommand/blob/main/cvmfs/log.txt

curl -s https://raw.githubusercontent.com/NeuroDesk/neurocommand/main/cvmfs/log.txt

assign the container name to a variable:

export container=itksnap_3.8.0_20201208

Then download the containers. An easy way is to use CURL:

curl -X GET https://object-store.rc.nectar.org.au/v1/AUTH_dead991e1fa847e3afcca2d3a7041f5d/neurodesk/${container}.simg -O

Or using aria2:

aria2c https://object-store.rc.nectar.org.au/v1/AUTH_dead991e1fa847e3afcca2d3a7041f5d/neurodesk/${container}.simg 

Singularity Containers and GPUs

Some of our containers contain GPU-accelerated applications. Here is an example that tests the GPU accelerated program eddy in FSL:

curl -X GET https://object-store.rc.nectar.org.au/v1/AUTH_dead991e1fa847e3afcca2d3a7041f5d/neurodesk/fsl_6.0.5.1_20221016.simg -O
git clone https://github.com/neurolabusc/gpu_test.git
singularity shell --nv fsl_6.0.5.1_20221016.simg
cd gpu_test/etest/
bash runme_gpu.sh

Transparent Singularity

The singularity containers can be also be used in combination with our Transparent Singularity Tool, which wraps the executables inside a container to make them easily available for pipelines. More information can be found here:

one example to do this is:

curl -s https://raw.githubusercontent.com/NeuroDesk/neurocommand/main/cvmfs/log.txt
export container=itksnap_3.8.0_20201208
git clone https://github.com/NeuroDesk/transparent-singularity ${container}
cd ${container}
./run_transparent_singularity.sh ${container}

3.6 - Windows 11 and Windows Subsystem for Linux

1. Install WSL

Follow the instructions to enable Windows Subsystem for Linux 2 in Windows 11: https://docs.microsoft.com/en-us/windows/wsl/install

2. Configure CVMFS, Singularity and LMOD (only needs to be done once)

Install build tools

sudo apt update
sudo apt install make gcc

Install singularity

export SINGULARITY_VERSION=3.9.3 VERSION=1.17.2 OS=linux ARCH=amd64
wget -q https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz 
sudo tar -C /usr/local -xzvf go$VERSION.$OS-$ARCH.tar.gz 
rm go$VERSION.$OS-$ARCH.tar.gz 
export GOPATH=${HOME}/go 
export PATH=/usr/local/go/bin:${PATH}:${GOPATH}/bin 
mkdir -p $GOPATH/src/github.com/sylabs 
cd $GOPATH/src/github.com/sylabs 
wget -q https://github.com/sylabs/singularity/releases/download/v${SINGULARITY_VERSION}/singularity-ce-${SINGULARITY_VERSION}.tar.gz 
tar -xzvf singularity-ce-${SINGULARITY_VERSION}.tar.gz 
cd singularity-ce-${SINGULARITY_VERSION} 
./mconfig --prefix=/usr/local/singularity 
make -C builddir 
sudo make -C builddir install 
cd .. 
sudo rm -rf singularity-ce-${SINGULARITY_VERSION} 
sudo rm -rf /usr/local/go $GOPATH

Setup Bindpaths for Singularity (e.g. in .bashrc)

export PATH="/usr/local/singularity/bin:${PATH}"
export SINGULARITY_BINDPATH='/cvmfs,/mnt,/home'

CVMFS

Follow the instructions here: https://www.neurodesk.org/docs/getting-started/neurocontainers/cvmfs/

LMOD

sudo apt install lmod

3. Use Neurodesk containers

sudo cvmfs_config wsl2_start

module use /cvmfs/neurodesk.ardc.edu.au/neurodesk-modules/*

Example usage of fsleyes:

ml fsl
fsleyes

List the available programs:

ml av