itk-demo-configdb¶

The itk-demo-configdb microservice is the central database of the detector microservices storing configurations, histogramm and more. It provides an openAPI interface to the functionality provided by the configdb-server python package. It allows you to access the configuration database via HTTP requests. For access from python one can also use the configdb-server package directly.

api: Webserver providing HTTP-API to ConfigDB, wrapper around configdb-server package.
pyconfigdb, python package: Python library to access HTTP-API. README
server, python package: Python library providing the ConfigDB server functionality. README
ui,: Web based UI to the ConfigDB. Deprecated, new version outsourced to runkey-manager

There are several repositories related to the configdb: - itk-demo-configdb, general configdb repo, serves as a webserver for the configdb-server code - configdb benchmarking, repository containing configdb-benchmarking scripts - runkey-ui, UI to create runkeys in the configdb

Setup¶

The itk-demo-configdb repository also includes some preconfigured docker-compose files in the example directory. These can be used to quickly set up a configdb instance. You only need to make sure that the following values in the .env file are set according to your local setup.

hostname of your system
uid of your user
gid of your user
timezone of your system
the docker directory, a directory where docker can store persistent data (like the database files), the docker user needs to have read and write access to this directory

For this you can use the following script.

Bash

./config

The docker compose file includes the following services:

configdb-api
mariadb server
phpmyadmin
runkey-ui

The services docker compose file includes the following services:

service-registry
etcd
dashboard-ui
restish

If you don´t need all of these services you can remove or comment them out from the docker-compose file.

You can start the services using the following command:

Bash

docker compose -f services_compose.yaml up -d
docker compose up -d

How to use¶

The configuration database system consists of two databases. The staging area and the backend database. The staging area is intended to be used while constructing a runkey (or other kinds of trees/graphs). After the runkey is constructed has to be committed. Its structure is checked and the runkey is then copied to the backend database. Once committed a runkey can not be modified. It is only possible to add additional notes (e.g. scans and results). If you want to edit an existing runkey, you can clone it into the staging area and make changes there. Once finished you can commit it as a new runkey. The old runkey will still exist in the backend database.

Browser UI¶

The runkey-UI container is part of the configdb-stack. It allows you to manage your runkeys via a GUI. When starting via the example docker compose files (explained here) it is running on port 5111. It can also be found on the dashboard running on port 80.

Runkeys¶

When starting the configdb-stack the runkey-import container will create an example runkey from the configs found in /example/configs/tree. More detailed information on how to add custom runkeys using the runkey-import container, the GUI or the API can be found here.

Accessing the configdb interface¶

The main way of accessing the configdb microservice is directly through the HTTP API. The API is documented here. The API is also available as a Swagger UI served from the microservice itself. For example, if the microservice is running on localhost:5000, the swagger UI can be accessed at localhost:5000/api/ui. The swagger UI provides documentation and a way to test the API endpoints.

CLI¶

To access the configdb api via the command line you can use the restish container found here and in the example stack. It gives you access to the API of all compatible microservices. The restish container is also included in the docker-compose files in the example directory.