Installation

Fahrtenbuch runs as a Docker Compose stack. You host it yourself; there is no hosted service.

Requirements

• Docker Engine with Docker Compose
• persistent storage for the database and backups
• for public access: a domain and an HTTPS reverse proxy (needed for passkeys and the Android app over the internet)

Services

Service	Image	Purpose
app	ghcr.io/cheinisch/fahrtenbuch	Web dashboard and REST API, port 3000
worker	ghcr.io/cheinisch/fahrtenbuch	Background jobs: geocoding, map matching, monthly report, cleanup
db	postgres:16-alpine	Database
redis	redis:7-alpine	Job queue
redis-insight	redis/redisinsight	Optional view into the job queue, bound to localhost

Image tags

Tag	Contents
latest	Latest release. Recommended.
v0.6.11, v0	A specific release, or the latest release of a major version.
dev, dev-<commit>	Built from every push to main. Includes preview features such as vehicle costs. For testing only.

Choose the tag with IMAGE_TAG in .env.

Quick start

git clone https://github.com/cheinisch/fahrtenbuch.git
cd fahrtenbuch
cp .env.example .env

Edit .env and replace all CHANGE_ME values. At least set:

Variable	Value
POSTGRES_PASSWORD	random password
JWT_SECRET, TOTP_ENCRYPTION_KEY	two different long random secrets
DEFAULT_ADMIN_USERNAME, DEFAULT_ADMIN_EMAIL, DEFAULT_ADMIN_PASSWORD	initial administrator
PUBLIC_BASE_URL, CORS_ORIGIN	your public HTTPS address, e.g. https://fahrtenbuch.example.de
WEBAUTHN_RP_ID, WEBAUTHN_ORIGIN	hostname and origin for passkeys

Optional settings such as SMTP, Google/Microsoft sign-in and Redis Insight are described in configuration. The environment template lists all variables.

Then start the stack:

docker compose up -d
docker compose ps

The application listens on port 3000 (APP_PORT). Open http://localhost:3000 locally, or your public HTTPS address. Database migrations run automatically on start.

First sign-in

Sign in with the administrator from .env. A setup assistant guides you through:

1. language and overview,
2. your own administrator password,
3. server status: public address, passkeys, time zone,
4. e-mail (optional; SMTP itself is set in .env),
5. geocoding and map matching,
6. sign-in and privacy (Google/Microsoft status, Gravatar),
7. a first vehicle (optional),
8. pairing the Android app.

You can change all of this later under Administration. Then create accounts for other users in Administration › User management; they get a first sign-in assistant.

caution

Docker Compose creates named volumes automatically. Never run docker compose down -v for a routine restart: it deletes the database and backups.

Try it first? A public demo runs at demo.fahrtenbuch.app.