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

Return to the regular view of this page.

User Documentation

1 - Neurodesk Overview

A flexible, scalable and easy to use data analysis environment for reproducible neuroimaging.

What is Neurodesk?

Neurodesk provides a containerised data analysis environment to facilitate reproducible analysis of neuroimaging data. At Neurodesk, we believe that reproducibility should be a fundamental principle underlying neuroscientific data analysis (1). Analysis pipelines for neuroimaging data typically rely on specific versions of packages and software, and are dependent on their native operating system. These dependencies mean that a working analysis pipeline may fail or produce different results on a new computer, or even on the same computer after a software update. Neurodesk provides a platform in which anyone, anywhere, using any computer can reproduce your original research findings given the original data and analysis code.

The Neurodesk environment relies on software containers and allows users to build and use containers to analyse neuroimaging data. Containers can be compared to virtual machines, in that they allow users to create a virtual, isolated computing environment with an operating system separate to that of the host machine. However, containers differ from virtual machines in that they virtualise software rather than hardware. Practically, this means that container images require few system resources to install, start-up quickly, and are easily portable between computers.

We recommend watching this excellent short video from the Australian Research Data Commons (ARDC) on research applications of software containers. To read more about Docker containers, visit the Docker webpage

More information:

In-depth information:

What applications are included in Neurodesk?

You can check out the complete list of these applications

How should I cite the tools I am using and Neurodesk itself?

See here

Background

Neurodesk originates from various projects at the Centre for Advanced Imaging that enabled running neuroimaging tools on HPCs and Linux workstations using software containers. The ideas and code from projects like “DICOM2CLOUD”. “transparent singularity” and “CAID” were combined during a hackathon project to create a “Virtual Neuro Machine”. The project was later renamed to Neurodesk and further developments were funded through the ARDC platform project “AEDAPT” with the goal to create a national platform for reproducible electrophysiology data analysis and sharing, accessible to all Australian researchers across a wide range of disciplines that conduct electrophysiological research.

References

  1. National Academies of Sciences, Engineering, and Medicine. 2019. Reproducibility and Replicability in Science. Washington, DC: The National Academies Press. https://doi.org/10.17226/25303.

MIT License

Copyright (c) 2021 NeuroDesk

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

1.1 - Applications

List of Applications.

Below is a list of the neurocontainer applications included in the most recent Neurodesk release.

To use these applications through the Neurodesk platform, find the correct instructions for getting started by selecting your computing environment details in the widget on our home page

Neurodesktop comes packaged with:

  • programming software (e.g., Visual Studio Code, python, git)
  • workflow systems (Nipype)-data synchronization utilities (Rsync, Rclone, Nextcloud, Owncloud)
  • system management tools (Lmod, Singularity, Htop)
  • additional resources (Imagemagic, Firefox, OpenSSH client)
  • access to Neurocontainers via the Neurodesk menu (see list below)

1.2 - How to cite us

How should you cite Neurodesk and the tools you use through the platform?

Citing Neurodesk

Please cite the Neurodesk paper and if you used Neurodesktop, add the version that was used (e.g. v2024-12-06).

Renton, A.I., Dao, T.T., Johnstone, T., Civier, O., Sullivan, R. P., White, D. J., … Narayanan, A. & Bollmann, S. Neurodesk: an accessible, flexible and portable data analysis environment for reproducible neuroimaging. Nat Methods (2024). https://doi.org/10.1038/s41592-023-02145-x

Check our preprint here Neurodesk Preprint

Citing specific tools

To guarantee reproducibility, we recommend specifying the name, version number and builddate for any containerised applications used through Neurodesk. You can find this information here.

In addition to citing Neurodesk, please remember to cite any papers associated with the tools you use. You find this information in the README.m for each tool, or when opening the application through the menu in Neurodesktop.

If you used any EEG/MEG/electrophysiology tools, please also cite the AEDAPT project.

Examples

Here are some example excerts of how to cite Neurodesk:

“TGV QSM (v1.0.0_20210629, Langkammer et al, 2015) was run in Neurodesk (v2024-12-06, Renton et al, 2022)”

“EEGlab (2020.0_20211026, Delorme & Makeig, 2004) was run in Neurodesk (v2024-12-06, Renton et al, 2022) part of the AEDAPT project.”

References

  1. Langkammer, C; Bredies, K; Poser, BA; Barth, M; Reishofer, G; Fan, AP; Bilgic, B; Fazekas, F; Mainero; C; Ropele, S. Fast Quantitative Susceptibility Mapping using 3D EPI and Total Generalized Variation. Neuroimage. 2015 May 1;111:622-30. doi: 10.1016/j.neuroimage.2015.02.041
  2. Renton, A.I., Dao, T.T., Johnstone, T., Civier, O., Sullivan, R. P., White, D. J., … Narayanan, A. & Bollmann, S. Neurodesk: an accessible, flexible and portable data analysis environment for reproducible neuroimaging. Nat Methods (2024). 10.1038/s41592-023-02145-x
  3. Delorme A & Makeig S (2004) EEGLAB: an open-source toolbox for analysis of single-trial EEG dynamics, Journal of Neuroscience Methods 134:9-21. doi: 10.1016/j.jneumeth.2003.10.009

1.3 - Discussion Forum

Discussion Forum on Github.

1.4 - Neurodesk FAQ

Frequently Asked Questions.

What is Neurodesk?

Neurodesk provides a containerised data analysis environment to facilitate reproducible analysis of neuroimaging data. Analysis pipelines for neuroimaging data typically rely on specific versions of packages and software, and are dependent on their native operating system. These dependencies mean that a working analysis pipeline may fail or produce different results on a new computer, or even on the same computer after a software update. Neurodesk provides a platform in which anyone, anywhere, using any computer can reproduce your original research findings given the original data and analysis code.

More information:

In-depth information:

What applications are included in Neurodesk?

You can check out the complete list of these applications

How should I cite the tools I am using and Neurodesk itself?

See here

Can I change the desktop resolution?

Yes,

In a VNC session run lxrandr to change the desktop resolution image

In an RDP session refresh the webpage to adjust to the new window size

Can I run Neurodesk on an HPC without Docker?

Yes, our project aims to run on the hardware you have access to. However, without docker support you cannot use our desktop interface NeuroDesktop but you can still use the command line interface NeuroCommand on HPC. This works well for batch processing on HPCs once you developed your pipeline in our desktop interface. If your HPC provides a desktop interface you can use all our graphical applications without any issues and the GUIs even work via SSH x-forwarding - it’s not the most performant experience, but it works well enough.

How can I export a jupyter notebook as a PDF?

By default we don’t have all extensions installed to do this to keep the neurodesktop small. So you will see an error when trying to do File -> Save and Export Notebook As … -> Webpdf

To get webpdf export to work, open a terminal and run:

pip install nbconvert[webpdf]
playwright install chromium

Is there reduced performance when using containers?

If you are running containers on Linux there is no performance penalty - on an HPC with a Lustre filesystem it can even be faster to run our containers than running natively on the filesystem (because meta data operations are shifted to the compute node - more information can be found here:

Rioux, Pierre, Gregory Kiar, Alexandre Hutton, Alan C. Evans, and Shawn T. Brown. ‘Deploying Large Fixed File Datasets with SquashFS and Singularity’. ArXiv:2002.06129 [Cs], 14 February 2020. https://arxiv.org/abs/2002.06129 ).

However, running Neurodesktop on Windows and Mac will have a performance penalty, because Linux runs in a Hypervisor on these systems. Also, it is important to understand filesystem operation bottlenecks that can occur when accessing files across system boundaries (e.g. processing DICOM files stored on Windows inside Neurodesk).

How can I see how many compute resources Neurodesk containers need?

In Linux the containers run as normal processes and you can use htop and top to inspect the resource footprint. For Windows and Mac the information is not readily available, however, we have written a guide here: Troubleshooting

Can I just use the containers without neurodesktop or neurocommand?

Yes, there are multiple ways of using the containers directly and we provide an overview here: https://www.neurodesk.org/docs/getting-started/neurocontainers/

Can I keep my modifications in the container?

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

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

Can I force a complete container download to my system?

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

For windows an example would look like this:

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

Freeview 7.2.0 crashes when I open files

Freeview (and Freesurfer!) need a valid license to work and we are not allowed to distribute a license with Neurodesk!

You can follow these steps to run freeview 7.2.0 and open your files:

  1. apply for a license (https://surfer.nmr.mgh.harvard.edu/registration.html) and paste this license in ~/.license

then run

echo "export FS_LICENSE=~/.license" >> ~/.bashrc
then start freeview 7.2.0 and it should all work perfectly.

Matlab asks me to reactivate after restarting the desktop

There is one workaround for this problem. Fix the mac address for your session by including this in your docker command:

--mac-address 02:42:ac:11:00:02

How to restart a Neurodesk Lab session?

In the jupyter menu, click on File -> Hub Control Panel:

image

Then “Stop My Server”

image

Then “Start My Server”

image

How to restart a stuck Neurodesk when running locally in Docker or using the NeurodeskApp?

Open Docker Desktop Dashboard. Find the container under “Containers” and delete the Container there.

VScode

Vscode is not starting up (or starts many many copies of itself …)

This problem seems to be caused by a corrupted config directory. To fix this, run:

rm -rf ~/.config/Code

Keyboard and Multi-Language support

I am using a European keyboard layout and I cannot type symbols that require the ALT-GR key (like @ or \)

This seems to be a bug in Guacamole and RDP in combination with certain browsers. There are a few workarounds you can try:

  1. Use the connection option “Desktop Fixed-Resolution (VNC)” instead of Desktop Auto-Resolution (RDP)
  2. connect to the desktop using an RDP client instead of the browser (https://www.neurodesk.org/docs/getting-started/neurodesktop/windows/#using-an-rdp-client)

Copy-Paste and Clipboard issues

How do I copy and paste text?

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

Note for Mac Users: The Safari Browser is currently not compatible for copy and paste with Guacamole. Please either use the Neurodeskapp or a Edge/Firefox on MacOS. You will need to use a combination of CTRL and Command shortcuts in order to copy and paste text between Neurodesktop and the host computer. For example, copy text from your Mac with Command+C and then paste it into Neurodesktop using CTRL+V. For the other way around, you’d use CTRL+C in Neurodesktop and then Command+V on the Mac.

I cannot copy and paste text within Neurodesktop using keyboard shortcuts

If you’re using Mac, you might be trying to use Mac keyboard shortcuts, but Neurodesktop is using Linux keyboard shortcuts (CTRL+C and CTRL+V) If you use the terminal, please see “I fixed my internet browser clipboard, but copy or paste still do not work in the terminal” below.

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

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

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

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

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

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

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

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

image

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

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

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

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

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

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

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

It is also possible that the text you are trying to copy includes special characters (e.g., non-English characters), which may cause Neurodesktop to not execute your paste command (including the non specials characters). Give special attention to the following characters:

  • Dash: the en (short) dash is the normal one and copies ok, but the em (long) dash is considered a special character. When in doubt, replace all the dashes in the text you want to copy with en dashes.
  • Quotation mark: a strictly vertical quotation mark is fine, but a slightly leaning quotation mark / an apostrophe are special characters. When in doubt, replace all quotation marks in the text you want to copy with vertical quotation marks.

If it still does not work, please report the problem and we will do our best to help you:

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

Docker, WSL, Memory

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

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

docker run hello-world

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

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

Windows users: WSL not installed properly

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

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

Docker_WSL_correct

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

Docker_WSL_incorrect

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

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

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

Windows users: Failure to connect to Neurodesktop in Firefox

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

Trouble installing neurodesk images

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

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

Docker_troubleshooting

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

Docker_update

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

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

If you are using Docker on MacOS

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

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

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

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

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

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

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

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

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

How to empty trash bin in Neurodesktop

If you have deleted files using the Neurodesktop GUI but your storage is not yet emptied, execute the following command in the terminal.

rm -rf ~/.local/share/Trash/

How can I contribute new containers?

We are still working on making this easier, but here is the current workflow to add new applications.

I couldn’t find the information I was looking for. Where can I get additional assistance?

Neurodesk is an open-source project that is always evolving. If you are experiencing an issue not listed here, you can reach out to us on Github. Post your question at https://github.com/orgs/NeuroDesk/discussions or open a new issue, so that we can aim to solve it and update our help documentation.

How do I get my files into Neurodesk?

It depends where you are running Neurodesk and where your files are. We provide many different ways from drag-and-drop, to cloud storage to file mounts in Storage in Neurodesk.

1.5 - Metrics

User metrics, analytics and service uptime

Docker metrics

Total Neurodesktop container pulls: Docker Pulls

Github metrics

RepositoryStarsOpen issuesLast Commit
neurodesktop
neurocommand
neurocontainers
transparent-singularity
example-notebooks
neurodesk.github.io
neurodesk-app

User metrics

Uptime metrics

1.6 - Release History

Previous releases of neurodesktop
Latest Version
2024-12-06

2024-12-06

  • updated QSMxT: v7.2.2
  • add heudiconv 1.3.1
  • add mriqc 24.0.2 20241108
  • add samsrfx v10.003
  • add palmettobug 0.0.1 20241119
  • add neurodock/pydesigner
  • Update dcm2niix version to 20241125
  • changed CVMFS servers
  • added -w workaround for docker on apple silicon into dockerfile
  • add static strace to /opt for container debugging
  • enabled VNC again and fix RDP auto resizing

2024-10-22

  • use cloudfront distribution only
  • workaround for kernel bug on arm64
  • add ipywidgets ipyvolume jupyterlab_widgets
  • add fsl 6.0.7.14
  • add QSMxT v7.2.1

2024-10-16

  • add jupyter-resource-usage plugin
  • disable VNC
  • remove updating of example directory on startup
  • update jupyter-server-proxy
  • add more CVMFS servers
  • Added relion 4.0.1.sm61 20240528
  • update aslprep to 0.7.0
  • update deepretinotpy to 1.0.5
  • add quickshear
  • add nighres 1.5.1
  • update bidscoin 4.3.3 and 4.4.0
  • Added bart 0.9.00
  • updated QSMxT to 7.1.0
  • Added mrtrix3src (latest version)
  • update VesselBoost to ver 1.0.0 by @KMarshallX in #301
  • add qmrlab
  • added niimath
  • updated fsl to 6.0.7.8
  • update aslprep to 0.7.2
  • update ants to 2.5.3
  • updated spinalcordtoolbox to 6.4
  • Update afni to 24.2.07
  • add dcm2niix
  • add micapipe 0.2.3
  • added brainnetviewer
  • Added brainlifecli
  • update fmriprep to 24.1.0
  • Update dsistudio 2024.06.12
  • add vmtk 1.5.0

2024-05-25

  • add new CVMFS CDN servers
  • add jupyter_scheduler and ipycanvas
  • update guacamole version to 1.5.5 and tomcat to 9.0.87
  • add rise extension for presentations
  • https://github.com/NeuroDesk/neurocommand/releases/tag/2024-05-25
  • fixed brkraw by @stebo85 in #268
  • QSMxT: v6.4.1 by @astewartau in #270
  • update mrtrix3 by @stebo85 in #271
  • QSMxT: v6.4.2 by @astewartau in #272
  • QSMxT: v6.4.3 by @astewartau in #274
  • update bidscoin to 4.3.2 by @stebo85 in #275
  • update fmriprep by @stebo85 in #277
  • add julia 1.9.4 by @stebo85 in #280
  • update dsi_studio by @stebo85 in #283
  • add glmsingle by @stebo85 in #284
  • ants 2.5.1 20240429 by @stebo85 in #285
  • QSMxT: v6.4.4 by @astewartau in #287

2024-03-27

  • Switched from singularity to apptainer
  • added (brkraw) and fixed multiple tools (mrtrix3, julia)

2024-01-12

  • fixed fsl GUI error, when starting fsl in VNC mode (the USER was not exported)
  • removed c.ServerApp.root_dir setting because it was causing an error when clicking on the Home button. Now it’s not possible to navigate outside of the homedirectory anymore in the side panel.

2023-11-28

  • fixed a bug where the /proc/cpuinfo file under ARM did not contain a MHz entry, which stopped Matlab from starting up
  • fixed a bug where the SINGULARITY_BINDPATH was not send in a jupyter notebook file

2023-10-29

  • bugfix: conda and mamba environments are now initialized correctly when neurodesktop starts up (not just in jupyter)

2023-09-20

  • the neurodesktop image is now multi-arch and supports x86 and ARM64
  • fixed recursive link creation in /data
  • switched to new cvmfs server geolocation DNS steering policy system: cvmfs[1,2,3].neurodesk.org resolve to 3 servers per region which are compared for speed by the client on startup
  • fixed recursive execution of bash shell inside a singularity container
  • fixed empty username
  • switched release tag naming scheme to YYYY-MM-DD instead of YYYYMMDD for better readability

20230628

  • directories can now be deleted in jupyter interface even if they contain files
  • moved startup configurations out of .bashrc
  • removed redundant chown of homedirectory (e.g. affecting windows startup time)
  • added git extension to juputerlab
  • more robust handling of CVMFS edge cases

20230531

  • included neurodesktop version in hostname
  • removed apt lists
  • triggered automount externally

20230525

  • used jupyter based image
  • fixed environment variables for nipype
  • fixed RDP upload permission errors
  • added symlink on home if /data is mounted

20221216

20221129

  • updated qsmxt to 1.1.13 (contributed by Ashley)
  • added nipype 1.8.3 (contributed by Steffen)
  • added mneextended 1.1.0 (contributed by David)
  • added new tool category “workflows”
  • added new CVMFS mirror server in Phoenix
  • added mimetypes so that nii/minc files now open in the respective applications
  • matlab licenses can now be saved from the activation GUI
  • update rstudio to 2022.07.2 (and R version to 4.1.2 with new additional packages, like brms)

20220813

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

20220701

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

20220329

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

20220302

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

20220222

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

20220128

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

20220121

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

20220111

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

20211220

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

20211207

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

20211028

  • added EEGLAB

20211018

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

20210929

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

20210923

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

20210918

  • added mriqc 0.16.1 and mrtrix 3.0.3

20210917

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

20210916

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

1.7 - Acknowledgments

This work is supported by the Wellcome Trust with a Wellcome Discretionary Award as part of the Chan Zuckerberg Initiative (CZI), The Kavli Foundation and Wellcome’s Essential Open Source Software for Science (Cycle 6) Program [313306/Z/24/Z]

This project was supported by an Australian Research Data Commons (ARDC) Platform project “Australian Electrophysiology Data Analytics PlaTform (AEDAPT)”.

nif uq

swinburne liege

This work benefits from services and resources provided by the EGI Federation with the dedicated support of CESNET-MCC, Indiana University’s Jetstream2 cloud and Australian Research Data Commons Nectar cloud.

Thank you to Google Cloud and AWS for providing cloud credits to support this project since 2024. We thank Oracle for Research for supporting our project from 2022 to 2023.

1.8 - Contribute

How to get involved.

Contributors: Find information about our current contributors and how you can join this vibrant community.

Code of Conduct: We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy neuroimaging community.

Documentation: Detailed guides to contribute your tutorial to the Neurodesk documentation.

Roadmap: Our Roadmap lists the current ideas we would love to work on and where we need help.

Add tools: If you have a new tool that enhances your work, we strongly encourage you to add it to our project.

2 - Getting Started

Getting Started

Release

Ensure you note the release date of the Neurodesktop container image during installation, as it is indicated in the docker run command, e.g.

version

We regularly update Neurodesktop for optimal performance and updated software. Check the Release History for past releases. To upgrade your container, replace the release number with your desired version. For replicable analysis pipelines, share the stable release number you used, enabling others to recreate your work environment anywhere.

Video tutorial

See below for a 14 minute tutorial on getting started.

2.1 - Local

For simple interface and local installation

2.1.1 - Neurodesk App

A cross-platform desktop application for Neurodesk: The easiest way to use Neurodesktop

Minimum System Requirements

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

Downloading Neurodesk App

Installing Docker

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

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

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.

Start

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

Local

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.

Server

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.

Settings

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

Additional Directory

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.

2.2 - Hosted

For quick access to Neurodesk on the cloud or HPC systems

2.2.1 - Bunya

Use Neurodesk on Bunya (only for researchers with access to Bunya!)

Neurodesk is installed at the University of Queensland’s supercomputer “Bunya”. 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

If you want to use GUI applications (fsleyes, afni, suma, …) you need to overwrite the temporary directory to be /tmp (otherwise you get an error that it cannot connect to the DISPLAY):

export TMPDIR=/tmp

NOTE: MRIQC has its $HOME variable hardcoded to be /home/mriqc. This leads to problems on Bunya. A workaround is to run this before mriqc:

export neurodesk_singularity_opts="--home $HOME:/home"

If you are missing an application, please contact mail.neurodesk@gmail.com and ask for the neurodesk installation to be updated on Bunya :)

2.2.2 - Nectar Virtual Desktop Service

Run neurodesktop in the Nectar Virtual Desktop Service (For all Australian Researchers)

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

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

  8. Click on “EXPLORE”. 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: image

  13. Click “OPEN DESKTOP ->”: image

  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/

2.2.3 - Play

Neurodesk Play is a publicly available service for accessing Neurodesk without any setup

2.2.4 - Google Colab

Neurodesk Singularity Containers for 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

image

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 in our example library

2.3 - Neurodesktop

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

Video tutorial

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

2.3.1 - Portable Unprivileged NeuroDesktop

An unprivileged option for running NeuroDesktop without Docker or Podman.

Minimum System Requirements

  1. At least 5GB free space for neurodesktop base image
  2. At least 8GB of RAM

Downloading TinyRange

TinyRange (https://github.com/tinyrange/tinyrange) is a lightweight runtime for running Virtual Machines and Containers. It runs without admin privileges and doesn’t need Docker or Podman installed to work.

If you already have a tinyrange installation you can also try an in place update

tinyrange update --confirm

Downloading QEMU

  • Windows: TinyRange already includes QEMU so you can skip this step.
  • Ubuntu: sudo apt install qemu-kvm
  • MacOS: brew install qemu

Installing TinyRange

  • Unzip the archive to some local path on your computer. It’s recommended not to extract it to a network drive.
  • Open a terminal in the extracted archive and run ./tinyrange login or tinyrange login on Windows.
  • Once you see the tinyrange:~# type exit.

Running NeuroDesktop

  • Open a terminal in the TinyRange folder and run
  • Windows: tinyrange login -c https://github.com/NeuroDesk/neurodesktop/raw/refs/heads/main/neurodesk.yml
  • Linux/MacOS: ./tinyrange login -c https://github.com/NeuroDesk/neurodesktop/raw/refs/heads/main/neurodesk.yml
  • Neurodesktop will start up. Copy and paste the Jupyterhub link (starting with 127.0.0.1) at the end of the output to a browser.
  • Use Control+C in the terminal to exit.

Folder Sharing

  • Windows: add --mount-rw C:/neurodesktop-storage to the tinyrange login command to share C:/neurodesktop-storage
  • Linux/MacOS: add --mount-rw ~/neurodesktop-storage to the tinyrange login command to share ~/neurodesktop-storage

The mounted directories will be visible under /shared inside Neurodesk.

For example on Windows run:

tinyrange login -c https://github.com/NeuroDesk/neurodesktop/raw/refs/heads/main/neurodesk.yml --mount-rw C:/neurodesktop-storage

Changing CPU Cores, RAM, and/or Storage

  • CPU Cores: Add --cpu 8 to set the VM to 8 CPU cores.
  • RAM: Add --ram 8192 to set 8GB of RAM for the Virtual Machine.
  • Storage: Add --storage 16384 to allocate 16GB of disk for the Virtual MAchine.

Enabling Hardware Acceleration

  • Windows: This might require admin privileges in some cases. Search in your start menu for “Turn Windows features on or off.”. Find “Hyper-V Hypervisor” or “Windows Hypervisor Platform” and make sure it’s enabled. Then restart your computer.
  • Ubuntu/Other Linux: It should already work out of the box. If not make sure your user account has permission to read/write /dev/kvm.
  • MacOS: No extra steps required. It already works.

2.3.2 - Linux

Install neurodesktop on Linux

Minimum System Requirements

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

Quickstart

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.

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:

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

  1. 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:
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-12-06 vnmd/neurodesktop:2024-12-06

or for podman:

podman volume create neurodesk-home &&
sudo podman run \
  --shm-size=1gb -it --privileged --user=root --name neurodesktop \
  -v ~/neurodesktop-storage:/neurodesktop-storage \
  --mount type=volume,source=neurodesk-home,target=/home/jovyan \
  -e NB_UID="$(id -u)" -e NB_GID="$(id -g)" \
  -p 8888:8888 \
  -e NEURODESKTOP_VERSION=2024-12-06 docker://vnmd/neurodesktop:2024-12-06
  1. Once neurodesktop is downloaded, leave the terminal open and check which server neurodesktop is running on (Avoid pressing CTRL+C).

image

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

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

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

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

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

Deleting neurodesktop:

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

  1. Click on the terminal from which you ran neurodesktop

  2. Press Ctrl-C

  3. Run:

docker stop neurodesktop
  1. Run:
docker rm neurodesktop

Installing Docker

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

RHEL/CentOS (yum-based)

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

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

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

Ubuntu/Debian (apt-based)

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

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

sudo apt-get update
sudo apt-get install 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-12-06 \
  vnmd/neurodesktop:2024-12-06

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

image

Using tensorflow (singularity container in neurodesktop)
singularity pull docker://tensorflow/tensorflow:latest-gpu
singularity run --nv tensorflow_latest-gpu.sif
python

import tensorflow as tf
print("Num GPUs Available: ", len(tf.config.list_physical_devices('GPU')))

image

Connecting to a running Neurodesktop session via a plain shell

You can start a neurodesktop container using docker or the neurodeskapp. If you want to connect to this running session using a plain shell you can do this as well:

docker ps
# note the name of the running container, e.g. neurodeskapp-49977

# now connect to this container
docker exec -ti neurodeskapp-49977 bash

# then switch to the jovyan user
su jovyan

2.3.3 - MacOS

Install neurodesktop on 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:

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
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-12-06 vnmd/neurodesktop:2024-12-06

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

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

image

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

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

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

  3. 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
  1. Type:
docker rm neurodesktop

2.3.4 - Windows

Install neurodesktop on Windows

Minimum System Requirements

  1. At least 3GB free space for neurodesktop base image
  2. Docker requirements. Details found under https://docs.docker.com/get-docker/
  3. If installing docker using WSL, 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:

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
docker volume create neurodesk-home
# This creates a docker volume to store your /home/jovyan data inside a docker volume

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-12-06 vnmd/neurodesktop:2024-12-06
  1. Once neurodesktop is downloaded, leave the terminal open and check which server neurodesktop running on (Avoid pressing CTRL+C). ]

image

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

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

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

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

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

Deleting neurodesktop:

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

  1. Click on the terminal from which you ran neurodesktop

  2. Press control-C

  3. Type:

docker stop neurodesktop
  1. Type:
docker rm neurodesktop

2.3.5 - Cloud

Run neurodesktop on cloud computing resources

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/

2.3.6 - Data Storage

Add storage to Neurodesktop

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:

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

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:

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

where you can click on “Shared Drive”:

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

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-12-06 vnmd/neurodesktop:2024-12-06

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:

image

and then add the paths required and hit Save:

image

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:

image

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

For more advanced users who prefer a command-line interface

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

2.4.1 - Linux and HPC

Install neurocommand on Linux, HPC

Ways of using Neurocommand in Linux and HPC:

  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:

Setup Instructions:

Install command line (e.g. running on Linux, HPC or CVL)

  1. Load singularity For optimal performance, ensure you are using Singularity version 3.x:
module load singularity/3.5.0
  1. Load aria2 (Optional) To speed up container downloads, you can optionally install or load aria2c:
module load aria2c
  1. Clone and Set Up the Repository Clone the repository into a directory with enough storage and ensure you are not using a symbolic link (to be sure run cd `pwd -P`). It’s recommended to perform this setup within a Python virtual environment (venv) or a 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 -P`
# OR, depending on your installation:
export APPTAINER_BINDPATH=`pwd -P`

Install Containers

  • If these steps are successful, the help will be displayed
  • Install all or only specific containers by following the instructions, e.g.:
  1. Search and Install Specific Containers To search for containers that have “itksnap” in the name:
bash containers.sh itksnap
  1. Install a Specific Version To install a specific version, (e.g., itksnap version 4.0.2 from 20240117):
./local/fetch_containers.sh itksnap 4.0.2 20240117

To 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

Add 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/
# OR, depending on your installation:
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!
  • 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), run:
module --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.

To update

1. Update the Neurocommand Repository

First, ensure your local repository is up to date by pulling the latest changes:

git pull

Next, rebuild Neurocommand by running:

bash build.sh

2. Update Containers

To update the containers, navigate to the neurodesktop directory and run:

bash containers.sh

3. Update Specific Modules

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 $@

2.4.2 - Windows

Install neurocommand on 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.4.3 - Visual Studio Code

Guide connecting your VS Code environment to Neurodesktop

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:

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"
}
  1. Close this VS Code window. Use steps in previous section to connect normally

Useful Additions

Plugins to view neuroimaging data inside VScode: niivue-vscode

image

2.5 - Neurocontainers

What neurocontainers are about

2.5.1 - CVMFS

Neurodesk Singularity Containers on 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://s1perth-cvmfs.openhtc.io/cvmfs/@fqrn@;http://s1fnal-cvmfs.openhtc.io:8080/cvmfs/@fqrn@;http://s1sampa-cvmfs.openhtc.io:8080/cvmfs/@fqrn@;http://s1osggoc-cvmfs.openhtc.io:8080/cvmfs/@fqrn@;http://s1brisbane-cvmfs.openhtc.io/cvmfs/@fqrn@;http://s1nikhef-cvmfs.openhtc.io:8080/cvmfs/@fqrn@;http://cvmfs.neurodesk.org/cvmfs/@fqrn@;http://cvmfs-frankfurt.neurodesk.org/cvmfs/@fqrn@;http://s1bnl-cvmfs.openhtc.io/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

You can use the list above, but you can also pick a subset of servers that are close to you or fit your usecase better. To better understand what to choose, we use the following CVMFS server setup:

These CVMFS Stratum 1 servers are hosted by the Open Science Grid and every server has a Cloudflare CDN alias that is correctly located through the Maxmind GEOAPI service in the CVMFS client:

  • Illinois, USA: s1fnal-cvmfs.openhtc.io:8080 -> cvmfs-s1fnal.opensciencegrid.org:8000
  • Sao Paulo, Brazil: s1sampa-cvmfs.openhtc.io:8080 -> sampacs01.if.usp.br:8000
  • Lincoln, Nebraska, USA: s1osggoc-cvmfs.openhtc.io:8080 -> cvmfs-s1goc.opensciencegrid.org:8000
  • Netherlands, Europe: s1nikhef-cvmfs.openhtc.io:8080 -> cvmfs01.nikhef.nl:8000
  • US: s1bnl-cvmfs.openhtc.io:8080 -> cvmfs-s1bnl.opensciencegrid.org:8000

This CVMFS Stratum 1 server is hosted by ARDC Nectar Cloud and also has a Cloudflare CDN alias.

  • Brisbane, Queensland, Australia: s1brisbane-cvmfs.openhtc.io -> cvmfs-brisbane.neurodesk.org

This CVMFS Stratum 1 server is hosted by Pawseys Nimbus Cloud and also has a Cloudflare CDN alias.

  • Perth, Western Australia, Australia: s1perth-cvmfs.openhtc.io -> cvmfs-perth.neurodesk.org

This CVMFS Stratum 1 server is hosted by AWS:

  • Frankfurt, Germany: cvmfs-frankfurt.neurodesk.org -> ec2-3-72-92-91.eu-central-1.compute.amazonaws.com

Then we have a Cloudfront CDN setup on AWS, which works by having one geolocation-steered domain: cvmfs-geoproximity.neurodesk.org:

  • 153.02 (Longitude),-27.46 (Latitude) -> cvmfs-brisbane.neurodesk.org
  • 115.86,-31.95 -> cvmfs-perth.neurodesk.org
  • -88.30,41.84 -> cvmfs-s1fnal.opensciencegrid.org
  • -96.66,40.83 -> cvmfs-s1goc.opensciencegrid.org
  • 4.90,52.37 -> cvmfs01.nikhef.nl
  • 8.68,50.11 -> ec2-3-72-92-91.eu-central-1.compute.amazonaws.com
  • -46.63,-23.54 -> sampacs01.if.usp.br

This domain is then used as a Cloudfront origin and can be accessed under cvmfs.neurodesk.org

Then we have 3 direct URLS without CDNs as well that are geolocation-steered: cvmfs1.neurodesk.org: South America -> sampacs01.if.usp.br North America -> cvmfs-s1fnal.opensciencegrid.org Default -> cvmfs-brisbane.neurodesk.org Europe -> ec2-3-72-92-91.eu-central-1.compute.amazonaws.com Asia -> cvmfs-perth.neurodesk.org

cvmfs2.neurodesk.org: North America -> cvmfs-s1goc.opensciencegrid.org Europe -> cvmfs01.nikhef.nl Default -> cvmfs-s1goc.opensciencegrid.org

cvmfs3.neurodesk.org: North America -> cvmfs-s1bnl.opensciencegrid.org Asia -> cvmfs-brisbane.neurodesk.org Default -> cvmfs-s1bnl.opensciencegrid.org Oceania -> cvmfs-perth.neurodesk.org

These servers are currently NOT working and are NOT YET mirroring our repository (we are waiting for RAL to come back online, then the others will mirror that):

  • UK: s1ral-cvmfs.openhtc.io:8080 -> cvmfs-egi.gridpp.rl.ac.uk:8000
  • Swinburne, Australia: s1swinburne-cvmfs.openhtc.io:8080 -> cvmfs-s1.hpc.swin.edu.au:8000
  • China: s1ihep-cvmfs.openhtc.io:8080 -> cvmfs-stratum-one.ihep.ac.cn:8000

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

Troubleshooting and diagnostics

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

# Change settings
sudo touch /var/log/cvmfs_debug.log.cachemgr
sudo chown cvmfs /var/log/cvmfs_debug.log.cachemgr
sudo touch /var/log/cvmfs_debug.log
sudo chown cvmfs /var/log/cvmfs_debug.log

sudo vi /etc/cvmfs/config.d/neurodesk.ardc.edu.au.conf
echo -e "\nCVMFS_DEBUGLOG=/var/log/cvmfs_debug.log" | sudo tee -a /etc/cvmfs/default.local
cat /etc/cvmfs/default.local
sudo cvmfs_config umount
sudo service autofs stop
sudo mount -t cvmfs neurodesk.ardc.edu.au /cvmfs/neurodesk.ardc.edu.au
# check if new settings are applied correctly:
cvmfs_config showconfig neurodesk.ardc.edu.au

cat /var/log/cvmfs_debug.log
cat /var/log/cvmfs_debug.log.cachemgr

2.5.2 - DataLad

Neurodesktop containers can be used with 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

2.5.3 - Docker

Neurodesk Docker containers

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/

2.5.4 - Open Recon

Neurodesktop containers can be used in Open Recon

1) add the installation of the Python MRD server to any recipe in https://github.com/NeuroDesk/neurocontainers

Make sure to adjust invertcontrast.py to your pipeline needs (or replace/rename other files from the Python MRD server:

--workdir='/opt/code' \
--install build-essential libxslt1.1 libhdf5-103 libboost-program-options1.74.0 libpugixml1v5 vim dos2unix git cmake g++ libhdf5-dev libxml2-dev libxslt1-dev libboost-all-dev libfftw3-dev libpugixml-dev \
--run='git clone https://github.com/ismrmrd/ismrmrd.git && \
  cd ./ismrmrd && \
  cmake . && \
  make -j $(nproc) && \
  make install' \
--run='git clone https://github.com/ismrmrd/siemens_to_ismrmrd.git && \
  cd siemens_to_ismrmrd && \
  mkdir build && \
  cd build && \
  cmake .. && \
  make -j $(nproc) && \
  make install' \
--run='pip3 install h5py ismrmrd matplotlib pydicom pynetdicom nibabel' \
--run='git clone https://github.com/ismrmrd/ismrmrd-python-tools.git && \
  cd ismrmrd-python-tools && \
  pip3 install --no-cache-dir .' \
--run='git clone https://github.com/kspaceKelvin/python-ismrmrd-server && \
  find /opt/code/python-ismrmrd-server -name "*.sh" -exec chmod +x {} \; && \
  find /opt/code/python-ismrmrd-server -name "*.sh" | xargs dos2unix' \
--copy invertcontrast.py /opt/code/python-ismrmrd-server/invertcontrast.py \

2) test the tool inside the container on its own first and then test through MRD server

convert dicom data to mrd test data:

cd /opt/code/python-ismrmrd-server
python3 dicom2mrd.py -o input_data.h5 PATH_TO_YOUR_DICOM_FILES

start server and client and test application:

python3 /opt/code/python-ismrmrd-server/main.py -v -r -H=0.0.0.0 -p=9002 -s -S=/tmp/share/saved_data &
# wait until you see Serving ... and the press ENTER
python3 /opt/code/python-ismrmrd-server/client.py -G dataset -o openrecon_output.h5 input_data.h5

3) submit the container to the https://github.com/NeuroDesk/openrecon/ repository

follow the template instructions

2.5.5 - Singularity

Neurodesk Singularity Containers

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. One way is to use CURL:

curl -X GET https://neurocontainers.neurodesk.org/$container.simg -O

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://neurocontainers.neurodesk.org/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}

2.5.6 - Windows 11 and Windows Subsystem for Linux

Use Neurocontainers on Windows 11 with WSL and Wayland Display Server

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


Initialize the neurodesk modules:

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

Example usage of fsleyes:

ml fsl
fsleyes

List the available programs:

ml av