Running the recoveryPortal Demo¶
The recoveryPortal project in gitlab contains a python script called start_demo.py in the src/ directory. This script can launch a number of ProperyTest middlelayer devices so you can experiment by changing parameters and then using the recovery portal to change them back.
Docker-based Test Environment¶
Docker can be used to instantiate a standalone instance of Karabo, along with a standalone Influx database, in order to test and experiment with the recovery portal in a self-contained environment.
Prerequisites¶
Docker installed and working on your local system
Internet connection
Access to git.xfel.eu
To check if your local docker installation is working properly, open a terminal window and run ‘docker ps’. It should return a (probably empty) list of running containers and no error messages.
xctrl@exflqr50660:~$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
xctrl@exflqr50660:~$
Docker Networking¶
The Karabo container and Influx database container in this tutorial will both be using docker bridge networking to communicate with each other. If you want to learn more about how this works, there is a networking-specific tutorial here: https://docs.docker.com/network/network-tutorial-standalone/
Services running inside docker containers can find each other over the local network just by using the container names as hostnames. Docker takes care of resolving container names into IP addresses on its internal bridge.
To take advantage of this, create a local docker bridge network on your system.
docker network create localinflux
Launch a Stand-alone Influx Database¶
To launch a fresh Influx database instance with an empty database to start, run this docker command:
docker run \
-d \ # run detached (in background)
--rm \ # do not persist data or DB state
--name=recoverydb \ # name/hostname of container
--network=localinflux \ # name of network bridge to use
-e INFLUXDB_DB=candrtest \ # ...
-e INFLUXDB_HTTP_AUTH_ENABLED=true \ # ...
-e INFLUXDB_ADMIN_USER=infadm \ # environment variables that
-e INFLUXDB_ADMIN_PASSWORD=admpwd \ # specify InfluxDB configuration
-e INFLUXDB_USER=infusr \ # ...
-e INFLUXDB_USER_PASSWORD=usrpwd \ # ...
influxdb:1.8 # name and version tag of image to run
On first execution, this will download the influxdb:1.8 image from the public docker registry. On subsequent executions, the local copy of the image will run.
When ‘docker run’ is called on an image, an instance of that image is executed. This executing instance is called a container. You can see your local image copies as well as running containers with the following commands:
docker image ls
docker container ls # or 'docker ps'
Use ‘docker ps’ to confirm you have a running container named ‘recoverydb’ before proceeding.
Build a Stand-alone Karabo Control System Image¶
The minimal Karabo system and recoveryPortal can both be built into one docker image. In order to build the image, clone the recoveryPortal project and browse to the
A Dockerfile is a text document that contains all the commands a user can call on the command line to assemble an image. Running ‘docker build’ starts with a base image (defined early in the Dockerfile with a FROM statement) and executes all the Dockerfile commands in order on that image to create a new image.
To build the recovery portal image, run:
docker build -t localhost/candrdemo .
...
---> 6abcadddac62
Step 10/13 : RUN echo ". karabo/activate" >> /root/.bashrc
---> Using cache
---> bb8cb2d71614
Step 11/13 : EXPOSE 44444/tcp 8080/tcp 8585/tcp
---> Using cache
---> 9969a612278f
Step 12/13 : COPY entrypoint.sh /
---> Using cache
---> 45ec7b3c1eed
Step 13/13 : ENTRYPOINT ["/entrypoint.sh"]
---> Using cache
---> 0ff4dfdc8820
Successfully built 0ff4dfdc8820
Successfully tagged localhost/candrdemo:latest
Use ‘docker image ls’ to confirm you have successfully built the candrdemo image.
Launch a Stand-alone Karabo¶
To launch the recovery portal Karabo demo:
docker run \
-d \ # run detached (in background)
--rm \ # do not persist data or DB state
--name=recoveryinst \ # name/hostname of container
--network=localinflux \ # name of network bridge to use
-p 55555:44444 \ # ...
-p 8080:8080 \ # ports to expose on the host
-p 8585:8585 \ # ...
-e KARABO_BROKER_TOPIC=<random_string> \ # ...
-e INFLUX_DBNAME=candrtest \ # environment variables that
-e INFLUX_QUERY_URL=tcp://recoverydb:8086 \ # specify initial Karabo parameters
-e INFLUX_WRITE_URL=tcp://recoverydb:8086 \ # ...
-e INFLUX_URL=tcp://recoverydb:8086 \ #
localhost/candrdemo:latest # name and version tag of image to run
The environment variables passed to the candr demo image are used to set device parameters of the InfluxDataLogger and DataLoggerManager devices. They set the device properties needed to find the local InfluxDB container. Notice they refer to the InfluxDB container simply by its container name ‘recoverydb’. Port 44444 inside the container is mapped to host port 55555 outside the container to expose the containerised Karabo system to a Karabo GUI client.
Use ‘docker ps’ to confirm you have a running container named ‘recoveryinst’ before proceeding.
Connect a Karabo GUI to it¶
With both containers running, any Karabo GUI can connect to port 55555 on your test host.
When your Karabo GUI is connected, inspect the device properties of the InfluxLogReaders, InfluxDataLogger, and DataLoggerManager to see it is configured to use the containerized InfluxDB.
Also, the entrypoint of this Karabo image automatically runs the recoveryPortal’s start_demo.py, so you should also see a number of ProperyTestMDL devices instantiated and ready.
Tear It All Down¶
When finished testing, simply stop both containers:
docker container stop recoveryinst
docker container stop recoverydb
Because the ‘–rm’ flag was used in the ‘docker run’ command, all data created during the test is not persistent and will be lost. You can start both containers again for a fresh test environment.