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 Docker Desktop website. If your system is not supported, please refer to the 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.0.0/surf_nemo_x86_64_v2.0.0.tar.xz
docker load -i $SURF_NEMO_DIR/surf_nemo_x86_64_v2.0.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.0.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.0.0/checksum_x86_64.txt
docker inspect --format='{{.Id}}' "surf_nemo:x86_64-v2.0.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.0.0/surf_nemo_arm64_v2.0.0.tar
docker load -i $SURF_NEMO_DIR/surf_nemo_arm64_v2.0.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.0.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.0.0/checksum_arm64.txt
docker inspect --format='{{.Id}}' "surf_nemo:arm64-v2.0.0" > $SURF_NEMO_DIR/checksum_installed.txt
diff $SURF_NEMO_DIR/checksum_installed.txt $SURF_NEMO_DIR/checksum_arm64.txt

Alternative Installation (via VirtualBox)

If Docker is not supported on your system or you experience compatibility issues, you can still use SURF-NEMO using Oracle VirtualBox. Differently from 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.