Skip to content

pyconfigdb

is a wrapper for the ConfigDB endpoints. It contains several functions to access the HTTP endpoints in python code. For more information on the functionalities, please refer to the ConfigDB API.

Installation

To install this package and use it simply install it via pip (preferably from inside a venv). This will also enable you to run the CLI by running pyconfigdb from you terminal.

Bash
pip install pyconfigdb --extra-index-url https://gitlab.cern.ch/api/v4/groups/33370/-/packages/pypi/simple
To upgrade run:
Bash
pip install --upgrade pyconfigdb --extra-index-url https://gitlab.cern.ch/api/v4/groups/33370/-/packages/pypi/simple

For more info on that package and the CLI please refer to the README of the pyconfigdb.

The cli is also available as a container. For an example please refer to the extended tutorial.

itk-demo-configdb

The itk-demo-configdb microservice is part of the readout-stack. 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.

Slides giving an overview of the itk-demo-configdb microservice can be found here.

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

Setup

Instructions on the setup of the configdb containers can be found under quick setup. A more generell microservice setup guide can be found here.

Quick 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 up -d
docker compose -f services_compose.yaml 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.

Links