Extended tutorial stack

Extended microservices stack including optoboard, felix, configdb and the new (wip) dashboard.

gitlab repository

Getting started

This small guide assumes familiarity with docker and the optoboard / felix software and will only cover how to start and configure the microservices in this repository.

For a more general introduction into docker and the operation of the felix and optoboard microservices, see Benedikts tutorial slides.

Starting a microservice

Before starting execute the config_all.sh script to set the environment for all stacks. To start a microservice simply change into the respective directory and execute:

Text Only

docker compose up -d

Note: when using VSCode you can install the docker add-on and start the docker containers simply by right-clicking the compose files and chosing "Compose Up" in each directory.

The services have to be started in a (somewhat) specific order, as some of them depend on each other.

It is adviced to start with the backing services including: - service-registry (container registration tool) - dashboard (accessible on port 80, gives overview over all started services) - dockge (container management GUI) - dozzle (container logs GUI) - rabbitmq (message queue needed for optoboard microservice) - mariadb (database backend used for configdb)

Than start the configdb stack, the compose file includes: - itk-demo-configdb (configdb api server) - runkey-ui (runkey editor GUI) - pyconfigdb (CLI container needed to import/export runkeys)

After bringing up the configdb use the following commands from inside the configdb directory to import the runkey from your filesystem to the configdb and commit it. Before importing the felix config and settings files can be changed, if needed for your local setup. Details on how to edit this runkey can be found here.

Bash

./cli import-rk /runkey/tutorial_runkey tutorial_runkey --author "Max Musterman" --comment "Extended tutorial runkey" --commit

To check whether the commit was successfull check if it shows up when listing the runkeys in the backend database.

Bash

./cli runkeys --backend

The tutorial_runkey can now be used by the felix-container to get its settings and the felix configuration files.

And than start the felix & opto microservices in this order: - felix microservice - optoboard microservice

The state of the felix-microservice should now be reflected in the topology view of the dashboard running on port 80. The topology screen is based on the runkey you committed.

Settings of the microservices

Some of the microservices (e.g. the felix ms) offer the option to configure their startup behaviour by changing their compose file. Information on the options for the felix ms can be found here.

Note the demi integration variables being used here.

Known issues

Note that the felix container by default will init, configure and start felixstar on startup. For now this behaviour is not propagted to the felix GUI correctly - meaning that the GUI will not reflect the correct felix state. If you want to operate the felix using the GUI it is adviced to turn of the automatic init, config and felixstar start or simply stop and start felixstar via the GUI once to get it into the right state.