Skip to content

Installation

SURF is distributed as a self-contained, virtualized platform to ensure a clean and straightforward installation experience with minimal impact on your host system.

This section guides you through the recommended Docker-based installation of SURF-NEMO.

Docker is available for Linux, macOS, and Windows. To check compatibility with your system, please refer to the Docker Desktop website. If your system is not supported, please refer to the Alternative Installation section.

Shell Compatibility

This guide assumes you're using the bash shell. If you use another shell (e.g., zsh), replace ~/.bashrc with the configuration file for your shell (e.g., ~/.zshrc). The surf_nemo command can be used from any shell, but you must have bash installed since the script uses it internally.

Supported Architectures

Currently, SURF-NEMO is available for the following supported architectures: x86_64, arm64. To determine the architecture of your machine, you can use the uname -m command.

Docker is a lightweight, OS-level virtualization platform that allows applications to run consistently and efficiently across multiple operating systems, including Linux, macOS, and Windows. It simplifies installation by packaging all dependencies into an isolated environment, reducing the need for manual setup.

If you’re new to Docker, we recommend exploring helpful resources like the official Docker documentation or the community-driven Docker Curriculum.

Installation Steps

Follow the steps below to install and configure SURF-NEMO using Docker.

  1. Create a working directory: 

    echo "export SURF_NEMO_DIR=~/work/surf_nemo" >> ~/.bashrc  # Adjust the directory path if needed
source ~/.bashrc
mkdir -p $SURF_NEMO_DIR

  2. Install Docker Desktop:
    Download and install the latest version of Docker Desktop, then launch it.

  3. Install the SURF-NEMO Docker image: Download the SURF-NEMO Docker image for x86_64 architecture. Note that the docker load command may take a few minutes to complete, due to the size of the image. 

    wget -P $SURF_NEMO_DIR https://www.surf-platform.org/repository/surf_nemo/surf_nemo_2.1.0/surf_nemo_x86_64_v2.1.0.tar.xz
docker load -i $SURF_NEMO_DIR/surf_nemo_x86_64_v2.1.0.tar.xz

  4. Set up the SURF Command Line Interface (CLI):
    Configure a shell alias named surf_nemo to run the platform from any terminal session: 

    wget -P $SURF_NEMO_DIR https://www.surf-platform.org/repository/surf_nemo/surf_nemo_2.1.0/surf_nemo.sh  
chmod +x $SURF_NEMO_DIR/surf_nemo.sh
echo "alias surf_nemo='bash $SURF_NEMO_DIR/surf_nemo.sh'" >> ~/.bashrc  
source ~/.bashrc

  5. (Optional) Verify the installation:
    Run the following commands: 

    surf_nemo --version
surf_nemo --help
    If the installation was successful, you should see the version number and help message.
    To further verify image integrity, you can compare the installed image checksum with the reference one: 
    wget -P $SURF_NEMO_DIR https://www.surf-platform.org/repository/surf_nemo/surf_nemo_2.1.0/checksum_x86_64.txt
docker inspect --format='{{.Id}}' "surf_nemo:x86_64-v2.1.0" > $SURF_NEMO_DIR/checksum_installed.txt
diff $SURF_NEMO_DIR/checksum_installed.txt $SURF_NEMO_DIR/checksum_x86_64.txt

  1. Create a working directory: 

    echo "export SURF_NEMO_DIR=~/work/surf_nemo" >> ~/.bashrc  # Adjust the directory path if needed
source ~/.bashrc
mkdir -p $SURF_NEMO_DIR

  2. Install Docker Desktop:
    Download and install the latest version of Docker Desktop, then launch it.

  3. Install the SURF-NEMO Docker image: Download the SURF-NEMO Docker image for arm64 architecture. Note that the docker load command may take a few minutes to complete, due to the size of the image. 

    wget -P $SURF_NEMO_DIR https://www.surf-platform.org/repository/surf_nemo/surf_nemo_2.1.0/surf_nemo_arm64_v2.1.0.tar
docker load -i $SURF_NEMO_DIR/surf_nemo_arm64_v2.1.0.tar

  4. Set up the SURF Command Line Interface (CLI):
    Configure a shell alias named surf_nemo to run the platform from any terminal session: 

    wget -P $SURF_NEMO_DIR https://www.surf-platform.org/repository/surf_nemo/surf_nemo_2.1.0/surf_nemo.sh  
chmod +x $SURF_NEMO_DIR/surf_nemo.sh
echo "alias surf_nemo='bash $SURF_NEMO_DIR/surf_nemo.sh'" >> ~/.bashrc  
source ~/.bashrc

  5. (Optional) Verify the installation:
    Run the following commands: 

    surf_nemo --version
surf_nemo --help
    If the installation was successful, you should see the version number and help message.
    To further verify image integrity, you can compare the installed image checksum with the reference one: 
    wget -P $SURF_NEMO_DIR https://www.surf-platform.org/repository/surf_nemo/surf_nemo_2.1.0/checksum_arm64.txt
docker inspect --format='{{.Id}}' "surf_nemo:arm64-v2.1.0" > $SURF_NEMO_DIR/checksum_installed.txt
diff $SURF_NEMO_DIR/checksum_installed.txt $SURF_NEMO_DIR/checksum_arm64.txt

Alternative Installation

Windows Subsystem for Linux (WSL)

On Windows, SURF-NEMO can be run through Windows Subsystem for Linux (WSL), which provides a native Linux environment directly on Windows without the overhead of full virtualization. This is the recommended alternative for Windows users.

Installation Steps

Follow the steps below to install and configure SURF-NEMO using WSL.

  1. Check system requirements:
    WSL 2 requires Windows 10 version 1903 or later, or Windows 11. To verify your build, open the Run dialog (Win + R), type winver, and press Enter. If your build is outdated, update Windows before proceeding or consider the Virtual Box installation option. For more details, refer to the Microsoft WSL documentation.

  2. Install WSL:
    Open PowerShell as Administrator and run: 

    wsl --install -d ubuntu
    This enables the required Windows features and installs the WSL 2 kernel with Ubuntu as the default distribution. Once complete, you will be prompted to create a Linux user account. After installation, verify the setup from PowerShell: 
    wsl -l -v                       # lists installed distributions and their WSL version
wsl --set-default-version 2     # sets WSL 2 as the default version, if needed

  3. Install Docker Desktop and enable WSL integration:
    Download and install Docker Desktop for Windows. After installation, open Docker Desktop → Settings → Resources → WSL Integration, enable integration for your Linux distribution (e.g., Ubuntu), and ensure Use the WSL 2 based engine is enabled.
    To verify that Docker is accessible from within WSL, open your WSL terminal and run: 

    docker --version
docker run hello-world
    If the hello-world container runs successfully, Docker is correctly connected to the WSL environment.

  4. Make the SURF-NEMO image accessible from WSL:
    Place the downloaded image file (e.g., surf_nemo_x86_64_v2.1.0.tar.xz) in a Windows directory such as C:\Users\<username>\Downloads. WSL usually maps Windows drives under /mnt/, so the file should be accessible at: 

    /mnt/c/Users/<username>/Downloads/surf_nemo_x86_64_v2.1.0.tar.xz

  5. Load the SURF-NEMO Docker image:
    From your WSL terminal, navigate to the directory containing the image and load it: 

    docker load -i /mnt/c/Users/<username>/Downloads/surf_nemo_x86_64_v2.1.0.tar.xz
    Docker's load command supports .tar.xz archives natively in a Linux environment. However, if needed, you may install xz utilities inside WSL: 
    sudo apt update && sudo apt install -y xz-utils

  6. Verify the image is loaded:

    docker images | grep surf_nemo
    The SURF-NEMO image should appear in the list. You can now proceed with the standard installation steps, starting from step 4.

VirtualBox

If Docker is not supported on your system or you experience compatibility issues, you can still use SURF-NEMO using Oracle VirtualBox. Unlike Docker, which uses OS-level virtualization, VirtualBox provides full system virtualization by emulating an entire hardware environment. This approach is particularly useful on systems where Docker cannot be installed or executed.

Installation Steps

Follow the steps below to install and configure SURF-NEMO using VirtualBox.

  1. Download and install VirtualBox:
    Download and install the latest version of VirtualBox for your operating system from the official VirtualBox website.

  2. Install the VirtualBox Extension Pack:
    Download the Extension Pack corresponding to your VirtualBox version from the downloads page, and install it. This enables support for USB devices, remote display, and other advanced features.

  3. Download the SURF VirtualBox VM image:
    Get the preconfigured Linux VM image from the official SURF distribution site.

  4. Import and run the VM:
    Open VirtualBox, select File > Import Appliance to load the downloaded VM image.

  5. Start the VM: Double-click on the VM image to open it and wait for the Linux environment to fully boot. The username and password for the VM are both set to: surf.

  6. Install SURF-NEMO within the VM: Inside the running Virtual Machine (VM), the Docker Engine is already installed and ready to use via the command line interface (CLI). Note that you cannot use Docker Desktop inside a VM running on Oracle VirtualBox. Instead, you can use the Docker CLI, which provides all necessary functionality to install and run SURF-NEMO containers. To verify that Docker is working, open a terminal in the VM and run: 

    docker run hello-world
    If you see the "Hello from Docker!" message, Docker is functioning correctly. You can now proceed with installing SURF-NEMO by following the Docker-based installation guide, starting from step 3.