jannes / openfairdb

Open Fair DB is the CreativCommons Backend of Kartevonmorgen.org

Open Fair DB

The backend for Karte von morgen written in Rust.

Schnittstelle: REST API

The Test-API is available under http://dev.ofdb.io/v0/.

The current API is documented within the openapi.yaml file. You can render the API documentation e.g. with the swagger editor:

• go to https://editor.swagger.io
• go to File -> import URL
• enter https://raw.githubusercontent.com/kartevonmorgen/openfairdb/master/openapi.yaml
• enjoy ;-)

An other way to see how the API can be used, you can open the network tab in the developer tools of your browser and see the requests that are made to https://kartevonmorgen.org.

If you want to use the API in your project, please contact us at [email protected] . When your aplication is running stable you can switch from the dev.ofdb.io to the prductive api.ofdb.io. The API might still change sometimes. We will try to let you know in that case.

Quick start

Download the latest build openfairdb_x86_64-unknown-linux-musl_v0.10.0.tar.xz, unpack and start it:

wget https://github.com/kartevonmorgen/openfairdb/releases/download/v0.9.3/openfairdb_x86_64-unknown-linux-musl_v0.10.0.tar.xz
tar xJf openfairdb_x86_64-unknown-linux-musl_v0.10.0.tar.xz
RUST_LOG=info ./openfairdb

Build

Requirements:

• Rust (nightly)
• SQLite 3.x

Installing Rust & Cargo

If you're using Ubuntu 18.04 LTS you can run

sudo apt-get install curl libssl-dev gcc
curl https://sh.rustup.rs -sSf | sh

On Windows you can download the installer from rustup.rs. (But don't forget to install a C++ toolchain first).

Installing SQLite & Diesel

On Ubuntu:

sudo apt-get install sqlite3 libsqlite3-dev
cargo install diesel_cli --no-default-features --features sqlite

Compile & Run

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

The required Rust toolchain and version is defined in rustc-toolchain and will be installed by Cargo on demand when building the project.

On NixOS you can build the project with:

nix-build -E '(import <nixpkgs>{}).callPackage ./default.nix {}'

Logging

RUST_LOG=debug ./target/debug/openfairdb

If you want to get stacktraces on panics use

export RUST_BACKTRACE=1

Mailing

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.

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 DATABASE_URL="/volume/openfairdb.sqlite" \
    -v "/var/openfairdb":/volume:Z \
    openfairdb:latest

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

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.

Domain Model

Note: Currently the rendered class diagram must be updated manually by uploading the contents of the file classes.puml to the PlantUML Online Editor and replace the link for the rendered diagram with one of the generated URLs.

License

Copyright (c) 2015 - 2018 Markus Kohlhase
Copyright (c) 2018 - 2021 slowtec GmbH

This project is licensed under the AGPLv3 license.