Installation and running NRP using Docker containers

See also

Source Installation

This installation guide is for users who want to try out the NRP locally on their machine, clone template experiments, or create new ones based on our template models. More expert users or developers who might want to change code directly in the Platform or add Gazebo plugins and robot controllers should install the NRP from source instead.

This installation uses Docker as the underlying package manager. It is technically possible for users to open a shell in the containers and hack them, but they must be aware that containers are replaced on Platform updates and all there changes inside containers will be lost. Of course, all user data, custom experiments and models are safe and kept between updates!

Note

It is our wish to provide an open and inclusive access to our platform, therefore users can freely download and install the NRP on their machines. However, we would like to remind all the NRP current and prospective users of our commitment to the EC Horizon 2020 guidelines and recommendations which regulate the use of publicly funded research and research applications for benign use only. You can read more about this in the HBP Opinion on ‘Responsible Dual Use’.

Guide Contents

• Installation and running NRP using Docker containers

  • Preliminary step

    • Microsoft Windows

    • macOS

  • Installation

  • Postliminary steps

    • Installing SpiNNaker

  • Connect to the Neurorobotics Platform

  • Troubleshooting

    • Docker network

    • Windows issues

Warning

Usage of low-bandwidth networks.

This install procedure involves downloading of several GBs from the Internet. Public WiFi or slow connections will take a long time or possibly fail.

Preliminary step

Microsoft Windows

Note

Linux/Mac users, skip this part.

1. Windows users have to first install WLS 2 and a brand of Linux on top of it from the Windows Store (we tested WSL with Ubuntu 18.04 and Ubuntu 20.04). See here for instructions.

2. Open an Linux terminal from the Windows start menu (in our case an Ubuntu menu item) and proceed with the next step.

macOS

Note

Linux/Windows users, skip this part.

Note

on macOS only Docker versions >= 18.03 are supported.

1. Add an alias into your hosts file:

   echo "127.0.0.1 host.docker.internal" | sudo tee -a /etc/hosts
   

2. Restart your computer.

Installation

This install procedure should work on any Linux OS, macOS (with Docker version >=18.03) and on Windows 10 if you did the preparatory part. Other operating systems have not been tested and it is likely they will not work with this bash script.

1. The first step is to install Docker on your system (on Windows, install it in Windows, not in the WSL Ubuntu).

   • Use the Docker installation guides for your system.

   • If you’re using Linux OS, for your convenience, we recommend to allow the Docker to run as non-root user, otherwise put an eye on a note at the end of the paragraph.

2. Download the installation script. The script should auto-update itself later when needed.

3. The following steps will install and configure the Docker images of the NRP on your system (assuming that Docker can run as a non-root user). Your user data will be stored in Docker volumes. So everything is cleanly self contained. You just need to specify the release type of the NRP.

chmod 755 nrp_installer.sh
./nrp_installer.sh install VERSION
# Option 1: ./nrp_installer.sh install latest
# Option 2: ./nrp_installer.sh install legacy

In order to install the latest release of the NRP (Python 3.8 compatible) use latest as VERSION. In case the VERSION parameter is set to legacy, then the script installs the legacy release of the NRP (v3.0.5 - Python 2.7 compatible). Note, that omitting VERSION parameter forces the script to install the latest release of the NRP. You can run the script without any arguments to get a list of other options, e.g. uninstall, restart, connect to containers (open a bash inside them) etc.

Note

In case for security reasons you do not want to grant the Docker privileges to be run as a non-root user, add -s option for the nrp_installer.sh after the command, i.e.: ./nrp_installer.sh install latest -s. This option runs the installation with required sudo privileges.

Postliminary steps

Installing SpiNNaker

Note

This step might only be necessary for users who own a SpiNNaker board and want to connect this board with the NRP.

By default, the NRP works with a 4-chip SpiNNaker board using the standard IP-address as shown here. To change the standard settings, please follow these steps:

./nrp_installer.sh connect_backend
# Open a new terminal and enter
nano ~/.spynnaker.cfg
# Modify the IP-address and board settings in the text file

More information on the SpiNNaker settings can be found in the SpiNNaker documentation.

# Back in the old terminal enter
./nrp_installer.sh restart

Connect to the Neurorobotics Platform

After running the installation script, in order to connect to the platform open your browser (Firefox and Chrome are officially supported) and go to the following link: http://localhost:9000/#/esv-private .

You will be prompted to enter a username and password. On local installs like this one, there is a default user “nrpuser” and password “password”. Creating new users is currently not possible from the user interface.

Troubleshooting

Docker network

If there are troubles setting up the Docker network, you can try a different subnet by changing it in the installer script.

Windows issues

In Windows install, communication with the Docker daemon has been reported. In that case, follow this:

• check the setting expose deamon on tcp://localhost:2375 in Docker;

• in Ubuntu add the line at the bottom of your $HOME/.bashrc (use the nano editor, for example):

  export DOCKER_HOST=tcp://localhost:2375