API usage

If you want to use the public API in your project, please contact us via helmut@kartevonmorgen.org.


The API is documented as an OpenAPI specification in the openapi.yaml file. A rendered version can be found at SwaggerHub.


The Test-API is available under


For production usage you can use


The API might still change sometimes. We will try to let you know in that case.

Data License

Make sure you use the Data appropriate to the ODbL-License.


All the information you need for development can be found in this chapter:

Quick start

Download the latest build, unpack and start it:

wget https://github.com/kartevonmorgen/openfairdb/releases/download/v0.12.0/openfairdb_v0.12.0.x86_64-unknown-linux-musl.tar.xz
tar xJf openfairdb_v0.12.0.x86_64-unknown-linux-musl.tar.xz
RUST_LOG=info ROCKET_SECRET_KEY="hPRYyVRiMyxpw5sBB1XeCMN1kFsDCqKvBi2QJxBVHQk=" ./openfairdb

NOTE: Don't (!) use this secret key! Generate your own!



  • Installation of Rust with the stable toolchain
  • SQLite 3.x

Development tooling

The installation of various development tools is automated by a just recipe named setup:

cargo install just
just setup

Check the configuration in .justfile if any of the recipe's steps should fail. Running the recipe repeatedly is also possible.

The setup includes the installation of a Git pre-commit hook in .git/hooks/.

Platforms and environments


On NixOS you can run nix-shell within the root of the repository to pull all required dependencies.


If setting up MacOS in order to build, be sure to install a C compiler via $ xcode-select --install. Otherwise cargo install will not behave as expected.


Install required packages:

sudo apt-get install curl libssl-dev gcc sqlite3 libsqlite3-dev

Periodic tasks

Both the development toolchain, tools and the Rust dependencies should be upgraded periodically by running the following just recipe:

just upgrade

Review the changes in the configuration files and commit them selectively as desired.

Build & Run


git clone https://github.com/kartevonmorgen/openfairdb
cd openfairdb/
cargo build




RUST_LOG=debug ./target/debug/openfairdb

If you want to get stacktraces on panics use



Most tests can be run as usual:

just test


cargo test

but some tests needs to be run within a real browser:

wasm-pack test --chrome


cargo build --release

Copy the final executable (./target/release/openfairdb) to the target directory of your server and make sure it gets executed as a service on startup.

Secret Key

The server uses a secret key to encrypt e.g. private cookies. In release mode it is required to define this secret key. This can be done by setting the environment key ROCKET_SECRET_KEY.

You can generate a key e.g. with OpenSSL:

openssl rand -base64 32

Further details can be found in the Rocket documentation.


Build the image

Build and tag the Docker image:

docker build -t openfairdb:latest .

The image is created FROM scratch and does not provide any user environment or shell.

Run the container

The executable in the container is controlled by the following environment variables:

  • RUST_LOG: Log level (trace, debug, info, warn, error)
  • DATABASE_URL: Database file path

The database file must be placed in a volume outside of the container. For this purpose the image defines the mountpoint /volume where an external volume from the host can be mounted.

The container exposes the port 8080 for publishing to the host.


docker run --rm \
    -p 6767:8080 \
    -e RUST_LOG="info" \
    -e DATABASE_URL="/volume/openfairdb.sqlite" \
    -v "/var/openfairdb":/volume:Z \

NOTE: Don't (!) use this secret key! Generate your own!

Extract the static executable

The resulting Docker image contains a static executable named entrypoint that can be extracted from any container instance (but not directly from the image itself):

docker cp <container id>:entrypoint openfairdb


To be able to send email notifications you need to define a sender email address. You can do this by setting the MAIL_GATEWAY_SENDER_ADDRESS environment variable. If you like to use the mailgun service you also need to define the MAILGUN_API_KEY variable with your API key and the MAILGUN_DOMAIN variable with the domain you are setup for mailgun.

DB Backups

At the moment the OpenFairDB does not support online backups. Therefore we use a simple script that copies the DB file once a day.


The following chapters outline the basic architecture using the C4 model.

In general we try to follow the principles of the Clean Architecture described by Robert C. Martin 1.

Clean Architecture


The diagrom below shows the general context of the OpenFairDB system.




The following diagram shows the dependencies of the components and the association to the respective layers.

Domain Model