Getting Started

TravStats is a self-hosted travel logbook. Getting from a clean server to a running instance with your first flight in it takes about ten minutes — most of it spent waiting for the Docker pull and the airport seed.

This page is the orientation. The three sub-pages walk you through each stage in detail.

The shape of a TravStats install

Three Docker containers on one private network, one named volume each:

• travstats-app — the application itself. Express backend serves the API on port 8000 internally; baked-in nginx serves the React frontend on port 80. The compose file exposes only port 80 to the host.
• travstats-db — Postgres 15 with PostGIS. Holds every flight, trip, achievement, setting, and audit-log entry you’ll ever produce. Daily pg_dump backups land on the same data volume; an optional WebDAV sync ships them off-host.
• travstats-ollama (optional) — local LLM (default gemma3:12b) used as fallback for email parsing when the built-in templates can’t handle a particular airline. Skip it if you only fly LH/LX/OS/SN/FR/U2/EW/W6 (the eight carriers with built-in templates) or if you’d rather enter unknown airlines manually.

The whole stack is one docker compose up -d. There is no app to install on the host, no database server to provision separately, nothing to configure outside the running containers — every setting that matters lives in the database, exposed via the admin UI in your browser.

What you’ll do, in order

1. Install — pull the compose file, set a database password, start the stack. ~3 minutes.
2. First run — open the browser, the setup wizard catches you, you create the admin account in five fields. ~2 minutes. After this you’re signed in and on the dashboard.
3. Use it — log a flight, scan a boarding pass, forward a booking email. The User Guide covers what each feature does. No order required; explore.
4. Update later — every few weeks a new release lands. Two commands. Migrations run automatically.

If something on step 1 or 2 goes sideways, the Troubleshooting page lists the symptoms people hit most often and what to do about each.

Prerequisites

Requirement	Minimum	Notes
OS	Any Linux that runs Docker	Bare metal, LXC, VM, NAS appliance — all fine
Docker Engine	24.x	Older Docker versions miss compose v2 features TravStats relies on
Docker Compose	v2	Built into recent Docker Desktop / Docker CLI; docker-compose (with hyphen) is too old
Disk	~1 GB	App + Postgres data; +5 GB if you keep Ollama with a 12B model
RAM	512 MB	+ ~4 GB if Ollama is running. Without Ollama, a Pi 4 handles it comfortably
Network	Outbound HTTPS	For the initial image pull. The running app only needs outbound access if you enable AirLabs/Aviationstack/OpenSky enrichment or set up SMTP

A reverse proxy (Cloudflare Tunnel, Caddy, nginx, Traefik, Tailscale) is optional but recommended if you want HTTPS or remote access. TravStats auto-detects HTTPS from X-Forwarded-Proto and sets the Secure flag on its session cookie accordingly. On a LAN-only HTTP deployment, set COOKIE_SECURE=false in .env so the browser doesn’t drop the cookie.

What you do not need

• No Node.js, npm, or Python on the host. Everything runs in containers.
• No external Postgres unless you specifically want to use one (the bundled db service is fine for ten users and a quarter-million flights).
• No API keys to start. AirLabs, Aviationstack, OpenSky, OpenAI, Anthropic — all of those enhance TravStats but none gate the core flows. Run blank, add later.
• No SMTP server to start. Single-user instances never need it; multi-user instances need it for invitation emails, but you can also create users manually under Admin → Users.

What gets configured where

There are two layers of configuration. The first time confuses people; once you see it, it’s obvious.

Layer	Lives in	Examples
Infrastructure	.env next to compose file	DB_PASSWORD, APP_PORT, optional COOKIE_SECURE / CORS_ORIGIN overrides for unusual proxies
Everything else	The database, exposed via Admin → Settings	Instance name, public URL, user cap, registration mode, all API keys, Ollama URL + model, SMTP, backup schedule, WebDAV target, log level

This split is deliberate: nothing about your TravStats install should require touching env files after first install. Change your SMTP password? Click in the admin UI. Switch from AirLabs to Aviationstack? Click in the admin UI. The only reason to ever edit .env again is to bump VERSION when you want to pin a new release.

Pick your starting point

If you’ve never run TravStats before, go straight to Installation.

If you’re upgrading from an older version that you set up months ago, jump to Updating — the release-tag table there explains what’s safe to pull blindly and when it pays to read the changelog first.