MacOS

Install neurodesktop on MacOS

Quickstart

1. Install Docker or Podman

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

Docker for MacOS by default runs with 2GB Memory. For actual workloads, 4GB Memory minimum for docker is highly recommended. You need to adjust this:

Open the Docker Desktop and Navigate to the Settings. Then navigate to the “Resources” section.
Increase the Memory slider from 2.00 GB to 4.00 GB (or greater)
Increase Swap slider from 1GB to 2GB (or greater)

For best performance on ARM Apple Silicon Hardware (M1/M2/M3) you need to enable Rosetta support in Docker: 0. If you are running Docker newer than 4.25.0 (126437) then you don’t need to do anything as it’s enabled by default already.

For Docker versions older than 4.25.0 (126437): Open the Docker Desktop and Navigate to the Settings. Then navigate to the “Features in development” section.
Activate “Use Rosetta for x86/amd64 emulation on Apple Silicon
Click “Apply & Restart”
Current limitations of running Neurodesk through Rosetta emulation on MacOS: FSLeyes, SPM, and EEGLAB are not starting up (Deactivate Rosetta to use these); external applications cannot be called from Matlab.

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

2. Run Neurodesktop

Use one of the following options to run Neurodesktop:

Option 1 (Recommended): Neurodesk-App

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

Option 2 (Advanced): Using Terminal

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

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

1.a) with a persistent home directory:

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

1.b) without a persistent home directory:

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

There is a bug in docker 3.3.0 for Mac that makes this command not run correctly so that there is no application menu when the desktop is started. Update your docker version if you see this!

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

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

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

We recommend using Chrome over Firefox as it has an option to hide the Toolbar in full screen mode (go to the menu bar, click on View, and uncheck “Always Show Toolbar in Full Screen”). This allows for Neurodesktop to fully utilise the whole of your screen.

If prompted, press on “Desktop Auto-Resolution” under “ALL CONNECTIONS”
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.
Neurodesk is ready to use! See the tutorials page for advice on how to use Neurodesk.

The browser can be closed anytime, and Neurodesktop will continue to run in the background. To reconnect to Neurodesktop, simply start over from step 3 above.

If you are using conda environments and you are installing packages or even new kernels, make sure to read this: https://www.neurodesk.org/tutorials-examples/tutorials/programming/conda/

Deleting neurodesktop:

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

Note

Note that any data that were saved outside of /neurodesktop-storage would be lost. Please make sure to move all your data to that folder before deleting neurodesktop.

Click on the terminal from which you ran neurodesktop
Press control-C
Type:

docker stop neurodesktop

Type:

docker rm neurodesktop

Using an RDP Client

Startup Neurodesktop using the following command:

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

If you want to connect via RDP using a different port, replace 3390 in the previous and next step with your port

Open your RDP client and connect to Computer localhost:3390

Use the following details to login if prompted

username: user
password: password

Using VNC

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

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

VNC allows for multiple desktop connections to same instance

VNC option for Neurodesktop on the browser does not support auto-resolution

Using a VNC Client

Startup Neurodesktop using the following command:

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

Open a VNC Client and connect to port 5901

Last modified April 26, 2024: update actions/checkout (5bd6058)