Install

Typical install is one or two Makefile commands. You need Docker and Docker Compose on the host.

Clone and start

git clone https://github.com/C05CDA/Frachtschiff.git
cd Frachtschiff
make setup    # creates deploy/.env and drive bind mounts
make start    # builds and starts db + api + web
Command Purpose
make setup Interactive wizard: admin user, drive paths, secrets, Compose overrides
make start Build and start the stack
make status Container status
make logs Follow logs
make stop Stop containers
make update Rebuild / rolling restart
make destroy Tear down (requires explicit confirmation)

Services

Compose runs three services under deploy/:

Service Role
db Postgres 16 - metadata only (named volume)
api Go API + background workers (internal :8080)
web Static SPA + reverse proxy to API; published as WEB_PORT (default 3000)

After start: open http://localhost:3000 (or your WEB_PORT). Health via the web proxy: /api/v1/health. The API is not published on the host by default - the web container proxies /api/.

Drive bind mounts

File data lives on host directories bind-mounted into the API at /data/drives/<label>. Setup writes these from the DRIVES env value. One path is enough for a normal single-drive cloud: 

DRIVES=main:/mnt/storage

Add more labels when you want a pool - local disks, or remote volumes already mounted on the host (for example network storage on a VPS, each as its own drive): 

DRIVES=drive-a:/mnt/disk250,drive-b:/mnt/remote-1,drive-c:/mnt/remote-2

Paths must exist and be writable by the API container. Frachtschiff does not mount remote storage itself - mount them on the host first, then point DRIVES at those paths. Drive data is not stored in Docker named volumes (only Postgres is).

First login. Use the admin username/password from setup (ADMIN_USERNAME / ADMIN_PASSWORD). Change the password after first login. ADMIN_PASSWORD only bootstraps an empty database - changing it later in .env does not update an existing admin.

TLS and reverse proxy

Frachtschiff expects you to terminate TLS at your own reverse proxy (Caddy, Traefik, nginx, etc.). Example snippets live in the main repo under deploy/examples/. See Security for forwarding-header and cookie notes.

What setup asks for

  1. Admin username and password
  2. Drive paths (validated exist / writable)
  3. Optional default tier replica counts
  4. HTTP port and related settings
  5. Generated deploy/.env and compose overrides

Advanced users can edit deploy/.env afterward - see Configuration.

Next: Configuration ยท Security