API usage

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

Documentation

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

Endpoints

The Test-API is available under

https://dev.ofdb.io/v0/

For production usage you can use

https://api.ofdb.io/v0

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.

Development

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!

Setup

Prerequisites

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

NixOS

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

macOS

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.

Ubuntu

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

Build

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

Run

./target/debug/openfairdb

Logging

RUST_LOG=debug ./target/debug/openfairdb

If you want to get stacktraces on panics use

export RUST_BACKTRACE=1

Test

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

Deploy

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.

Docker

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.

Example:

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

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.