Instructions to run a openroberta lab server using DOCKER

tl;dr

to run the openroberta lab on a local win or linux system, install docker, select (unused) directoriers for the data base and for temporary files (for crosscompilation for real robots), then run one command of the example section below.

Introduction

A lot of teachers, companies and people have reasons not to use our online lab at https://lab.open-roberta.org. Even if we prefer if you use the official lab, this text describes how to run a local installation of the lab :-).

Almost all server, laptops, workstations are powerful enough to run the lab with some hundred users. You can run the lab on windows10 and linux systems (Ubuntu, Debian, ...). A RaspberryPI is possible, but due to the slow SD card, it doesn't perform as good as the systems mentioned before. The network, the server is part of, may be connected to the internet or not. Note, that during setup connection internet acces is mandatory.

To have a real lightweight setup and operating, we are using docker.

Initial Setup and First Run

For the initial setup you need access to the internet.

First install docker on your computer. Check, that the docker demon is working. You'll find a lot of resources on the internet about installation and checking. On windows, you need docker desktop. This is available on linux, too. I prefer the bash and never used it.
you need a directory for the data base. The directory may not exist or be empty. In this case an empty data base is created automatically. Otherwise it must contain a valid data base, for instance from earlier runs of the lab (on the same or any other system).
you need a directory for temporary files used by the various crosscompiler. The directory may not exist or exist and even contain files. But it will be crowded with sources and binaries. From time to time you should remove the garbage, otherwise you'll run out of space (for a typical laptop, this will take a very, very long time, but it can happen). If you use no real robots, then you will not use crosscompiler and the directory is not used. But it must be declared.
you have to select the version of the lab server. If you look at https://hub.docker.com/r/openroberta/standalone/tags, you get a list of the versions ("tags") we have stored at dockerhub. It is likely that you select the highest version number for your local server. From time to time you may look for newer versions and switch.
When the local lab is started for the first time, this takes some time, because the lab image is pulled from dockerhub. You need internet connection for the pull (not for the later runs of the lab).
start the lab using a command from the example section below. The container gets the name you select, in the example my-local-lab. The internal container port 1999 is mapped to the external port 8080 (you can change it, 80 is a sensible value for http :-).
Check for success, e.g. by docker ps or with docker desktop. The container should be running.
Assuming, that your computer name is cavy, point your browser to http://cavy:80, select the simlutor plugin, write a small program and run the simulator to check your installation.
Later you may stop the container: docker stop my-local-lab and remove it: docker rm my-local-lab. The data base is not lost. For stopping you may use docker desktop. If you don't remove the container, you have to select new names for every start. You may omit the --name parameter and get a name generated by docker. In any case: remove exited container, they waste space!

Regular Operation

switch your computer on, start the docker demon, start the lab. That's it.

Remarks

logging of the lab server goes to the console. Use docker log my-local-lab to see the log.
when you specify the data base directory or the directory for temporary files, use always a full path (as in the examples)
you may want to start the lab when the computer is switched on (init). There are descriptions on the net how to do that for all operating systems. See below for an example for linux.
specify the robots you want to support in the -d robot.whitelist and -d robot.default parameters. Currently our start page expects sim as the first and the default robot as the second. Furthermore the default robot must support simulation and must be declared as default robot. This is user-unfriendly and will change in the future. If you omit the two parameters, you get all plugins. That is ok. The list of all plugins available currently is:
- sim
- ev3lejosv1, ev3lejosv0, ev3dev, ev3c4ev3, nxt
- spike prime
- microbit, botnroll, nao, bob3, sensebox, mbot, mbot2, edison, festobionic
- uno, nano, mega, nano33ble, unowifirev2
- thymio
- calliope2017NoBlue, calliope2017, calliope2016
- wedo
examples to start some plugins (append these parameters to the example commands below):
- calliope and microbit only: -d robot.whitelist=sim,calliope2017NoBlue,microbit -d robot.default=calliope2017NoBlue
- all Lego robots: -d robot.whitelist=sim,ev3lejosv1,ev3lejosv0,ev3dev,ev3c4ev3,nxt,spike -d robot.default=ev3lejosv1
- some arduinos: -d robot.whitelist=sim,ev3lejosv1,uno,unowifirev2,nano,mega,nano33ble -d robot.default=ev3lejosv1
if the lab is stopped, you may backup the data base by simply copying, zipping or tarring the data base directory.

Example commands

On my windows 10 I start the lab from cmd with a data base located at D:\data\db and the directory for temporary files located at D:\tmp\openrobertaTmp:

docker run -d --name my-local-lab -p 8080:1999 -v D:\data\db:/opt/db -v D:\tmp\openrobertaTmp:/tmp/openrobertaTmp openroberta/standalone:5.0.11

On my ubuntu I start the lab from bash with a data base located at /data/db and the directory for temporary files located at /tmp/openrobertaTmp:

docker run -d --name my-local-lab -p 8080:1999 -v /data/db:/opt/db -v /tmp/openrobertaTmp:/tmp/openrobertaTmp openroberta/standalone:5.0.11

Miscelleneous

We generate docker images for two architecture: x64 (almost always :-) or arm32v7 (for RaspberryPi).
The following primitive init script works for linux (and RaspberryPI). First it stops and removes all containers, then it starts the standalone lab. Obviously this script only works nicely if no other container are running on that machine:

#!/bin/sh
### BEGIN INIT INFO
# Provides:          openrobertalab
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: standalone openrobertalab service
# Description:       Start, stop and restart the standalone lab
### END INIT INFO
docker stop $(docker ps -a -q)
docker rm $(docker ps -q -f status=exited)
case "$1" in
    start|restart) echo 'openroberta standalone lab start'
                   docker run -d -p 80:1999 -v /opt/ora-db:/opt/db openroberta/standalone-arm32v7:4.1.2 -d robot.whitelist=sim,microbit
                   ;;
    stop)          echo 'openroberta standalone lab stop'
                   ;;
    *)             echo "invalid command \"$1\" for openroberta standalone lab init script. Usage: $0 {start|stop|restart}"
                   ;;
esac

it is likely, that you want to access the lab using https. In this case you have to run for example apache2 or nginx. This is quite easy. You find examples of setups in directory Docker/openroberta/conf of out GitHub repo.
if you need more robust operation of the server, e.g.
- data base access and/or backup when the lab is running (This requires a container running a data base server).
- automatic restart if the server is frozen. This is unlikely to happen, but if the server is unattended, it makes sense. ... then you should use the docker setup of our production server, which has this and more. It is more demanding from a technical point of view, but described in our git repo in file Docker/_README.md in detail. Please contact me (address below) and I support your setup.

do not hesitate to ask us or send corrections and proposals to reinhard.budde at iais.fraunhofer.de

Home | Community | Installation | Team