OpenKeg: The Lightweight Backend of the Musikverein Leopoldsdorf

This backend especially written for the Musikverein Leopoldsdorf, provides the functionality to authenticate against a directory server, provides a REST access to them and provide a REST interface to the archive.

Build

The project can be built with

cargo build --release

Setup

After build some setup is required such as the configuration.

RSA Keys

Keg uses RSA keys for signing JWTs in the PEM format. The following commands will generate a private key, a public key and an X.509 certificate which is valid for one year.

Generate the keys and the certificate

openssl req -x509 -newkey rsa:4096 -days 365 -utf8 -nodes -outform PEM -keyform PEM -keyout keg-private-key.pem -out keg.crt -sha512
openssl rsa -in keg-private-key.pem -pubout -inform PEM -outform PEM -out keg-public-key.pem

Docker

The application can also be setup with docker. Please refer to doc/dockerhub-overview.md for further information.

Configuration

You may copy the example configuration and change the parameters as required. Note that the configuration contains sensitive data such as the passwords to the directory or the database servers. This means that you should change the permissions to the configuration file such that only the user who runs application can read it.

As an alternative you might want to only omit these sensitive attributes and provide them as environment variables as described in the Rocket Configuration Section. The difference is that in this application, the prefix is KEG_ instead of ROCKET_. This is especially useful for container environments as in kubernetes or docker.

ℹ️	Due to unknown reasons it is currently not possible to override the default config file location.

The example configuration

link:keg.example.toml[role=include]

Markdown Documents

Markdown documents can be served as document types. A typical use-case for this to let the API expose documents from another service such as Nextcloud. To use it, the different document type mappings must be configured below the working directory of the server. This may not seem very convenient at the first glance when using a directory from another service, but there are options to evade this limitation depending on your setup:

• use a symlink, the simplest and recommended option

• mount rebind, useful when an advanced setup is required

Development

In order to use the pre-commit hook for formatting the code before every commit, just run make in the project root once.

Informal Coding Rules

Some rules cannot be expressed via the .editorconfig as they are often semantic and subject of taste.

Syntactic Rules

• Begin log messages uppercase

Coding Style Rules

• Prefer functional way over imperative

OpenAPI

This application hosts its own OpenAPI specification in order to document the rest interface. However, this does not include any frontends such as Swagger or RapiDoc. This leads it up to the user whatever they want to use. The schema definition is located at /api/v1/openapi.json.

The application provides the possibility to serve a self-contained frontend for OpenAPI. In order to use it, one has to set serve_static_directory = true in the configuration and set the appropriate static_directory_path and static_directory_url.

Warning

It is your responsibility to provide the files for the frontend and configure it properly. For this reason, it is disabled by default.

Name Origin

As in many music societies, the consumption of kegs is common in the Musikverein Leopoldsdorf. This makes them mandatory to be open — a prefix which is also used for many open source projects.