The compose pages name postgres:18, list the volume path for 18 and for 14 to 17, and say that changing a database's major needs pg_upgrade or a backup and restore. The move steps say to carry the install's own environment variables, container name and port over, and to append the passwords and COMPOSE_FILE to the existing .env instead of replacing it, so later plain docker compose commands, the ones in Updating included, keep using the Postgres file instead of starting TREK on the old travel.db. The pages also say which data is lost to an anonymous volume, which compose service waits for the database, what tables that differ from the Postgres schema mean, and how to recover from a first start without a password.
9.3 KiB
Install: Docker Compose
Production-ready setup using Docker Compose with security hardening enabled.
Compose File
See https://github.com/liketrek/TREK/blob/main/docker-compose.yml
Security Hardening Explained
The compose file ships with several hardening options enabled by default:
| Setting | What it does |
|---|---|
read_only: true |
Mounts the container filesystem read-only; only the two mounted volumes (/app/data, /app/uploads) and /tmp are writable |
security_opt: no-new-privileges:true |
Prevents the process from gaining additional Linux privileges via setuid/setgid executables |
cap_drop: [ALL] |
Drops all Linux capabilities from the container |
cap_add: [CHOWN, SETUID, SETGID, KILL] |
Adds back only what the container needs: the first three let the entrypoint drop privileges to the node user, KILL lets dumb-init pass the stop signal on to it, so docker stop shuts TREK down cleanly instead of killing it |
tmpfs: /tmp:noexec,nosuid,size=128m |
Mounts a 128 MB in-memory /tmp; required because the container root is read-only |
Note (Docker from snap): If you installed Docker via
snap(config under/var/snap/docker/...),no-new-privileges:truewill prevent the container from starting withexec /usr/bin/dumb-init: operation not permitted. This is a snap/AppArmor limitation, not a TREK issue — install Docker from the official apt repository instead, or removeno-new-privileges. See Troubleshooting.
Volumes
| Host path | Container path | Contents |
|---|---|---|
./data |
/app/data |
SQLite database (not used with TREK_DB_URL), logs, .jwt_secret, .encryption_key, pre-migration and pre-restore copies |
./uploads |
/app/uploads |
Uploaded files (photos, documents, covers, avatars) |
Named Volumes
The compose file above uses bind mounts (./data, ./uploads). You can switch to Docker named volumes, which are fully managed by Docker and not tied to a specific host path. See the Docker Compose volumes reference for all options.
services:
app:
# ... (rest of service config unchanged)
volumes:
- trek_data:/app/data
- trek_uploads:/app/uploads
volumes:
trek_data:
trek_uploads:
Docker creates the volumes automatically on first docker compose up. Use docker volume ls and docker volume inspect to manage them.
Optional storage seed
A commented line mounts a storage-config.json file from the compose folder read-only into the data directory. Uncomment it to provision file storage once on the first start. See Admin-Storage.
Healthcheck and Logs
The compose file includes a healthcheck that polls /api/health every 30 seconds and follows a changed PORT, so docker ps shows healthy once TREK is up. It also limits the container log to three files of 10 MB each, because Docker keeps every line forever by default.
Environment Variables
The compose file has no env_file: key, so a .env placed alongside docker-compose.yml is used only for ${VAR} interpolation — a value reaches the container only if a line in the environment: block references it. Four entries are wired that way:
# .env
ENCRYPTION_KEY=<output of: openssl rand -hex 32>
TZ=Europe/Berlin
LOG_LEVEL=info
ALLOWED_ORIGINS=https://trek.example.com
The commented HTTP_PROXY / HTTPS_PROXY / NO_PROXY lines are interpolated as well, so uncommenting them is enough to pick their values up from .env.
Every other variable — APP_URL, the OIDC block, FORCE_HTTPS, TRUST_PROXY, ADMIN_EMAIL/ADMIN_PASSWORD, the MCP limits — ships as a commented literal. Uncomment the line in docker-compose.yml and put the value there; setting it in .env alone has no effect.
A few variables are not in the compose file at all, among them FILE_UPLOAD_LIMIT_MB (the upload limit for files, 50 MB by default) and RESTORE_FROM_BACKUP (a backup ZIP to restore on the very first start, see Backups). Add a line for them to the environment: block yourself.
Some optional variables ship as commented lines, ready to uncomment: LLM_TIMEOUT_MS and LLM_MAX_OUTPUT_TOKENS for AI parsing, the VAPID_* keys for Web Push, TREK_PLACES_* and PLACES_API_KEY for place search, AMAP_*, UNSPLASH_ACCESS_KEY, GOOGLE_LIST_DATA_BASE and TREK_WIKI_DIR. Rootless Podman users will also find HSTS_INCLUDE_SUBDOMAINS, COOKIE_SECURE and ALLOW_LINK_LOCAL_IPS there.
APP_URL is usually not needed. TREK resolves its public base URL as APP_URL → first ALLOWED_ORIGINS entry → http://localhost:<PORT>, so the ALLOWED_ORIGINS value above already gives OIDC redirect URIs, passkey origin checks and the links in email notifications the correct origin. Uncomment APP_URL only when the public base URL has to differ from the first allowed origin.
For a full description of every variable, see Environment-Variables.
Image Tags
Five tags are available:
| Tag | Example | Behavior |
|---|---|---|
latest |
mauriceboe/trek:latest |
Always the newest release across all major versions |
| Major version | mauriceboe/trek:5 |
Latest release pinned to that major version |
| Minor version | mauriceboe/trek:5.0 |
Latest patch of that minor version; never moves to the next minor. Published from 5.0.0 on |
| Full version | mauriceboe/trek:5.0.0 |
Exact release; never changes |
latest-pre |
mauriceboe/trek:latest-pre |
Test build of the next version; not for production |
The compose file above uses latest. To pin, change the image: line:
image: mauriceboe/trek:5 # track major version 5
image: mauriceboe/trek:5.0 # stay on 5.0.x patches
image: mauriceboe/trek:5.0.0 # pin to exact release
Start TREK
docker compose up -d
Check the logs:
docker compose logs -f
HTTPS and Reverse Proxy
This compose file is designed for deployments where a reverse proxy (nginx, Caddy, Traefik) terminates TLS in front of TREK. To enable HTTPS redirects and secure cookies, uncomment FORCE_HTTPS=true and TRUST_PROXY=1.
See Reverse-Proxy for complete proxy configuration examples.
Running on Postgres
docker-compose.postgres.yml runs TREK beside a postgres:18 service instead of the SQLite file. Its db service keeps the database in a named volume and publishes no port, and the app service (container trek) waits for the database's health check before it starts. The app service sets only a few environment variables; add the others you need (APP_URL, FORCE_HTTPS, OIDC, SMTP and so on) as in docker-compose.yml.
The volume path depends on the Postgres major version: postgres:18 keeps its data under /var/lib/postgresql, the images for 14 to 17 under /var/lib/postgresql/data. Change the image tag and the volume path together, and only for a new database. A database stays on the major it was created with, so when you update the compose file later, keep your image tag and volume path; moving to another major needs pg_upgrade or a backup and restore, never just a new tag. See Database: Postgres.
Add two passwords to the .env file beside the compose file, together with COMPOSE_FILE, then start it:
printf '\nCOMPOSE_FILE=docker-compose.postgres.yml\nPOSTGRES_ADMIN_PASSWORD=%s\nPOSTGRES_PASSWORD=%s\n' '<a long random value>' '<another long random value>' >> .env
docker compose up -d
The command appends to .env, so the values already in it, such as ENCRYPTION_KEY, stay. COMPOSE_FILE makes every later docker compose command in this directory use docker-compose.postgres.yml without -f, including the ones in Updating. Without it, a plain docker compose up -d reads docker-compose.yml and starts TREK on the SQLite file instead.
POSTGRES_ADMIN_PASSWORD is the password of the database's superuser postgres, which on the first start only creates the role trek. POSTGRES_PASSWORD is the password of trek, the role TREK connects as: it owns TREK's database and is not a superuser, so a crafted backup restored into it cannot reach the database container. That password goes into TREK_DB_URL, so use URL-safe characters or percent-encode it. Without either password the database does not initialize and TREK does not start. An install made with an older version of the compose file connects as a superuser; Database: Postgres shows how to move it. To run it against a database that already exists elsewhere, use the plain docker-compose.yml and set TREK_DB_URL yourself.
Read Database: Postgres before you use it. It covers the requirements, SSL, backups and restores, and the limits of a Postgres install.
Next Steps
- Environment-Variables — full variable reference
- Reverse-Proxy — HTTPS configuration
- Updating — how to pull a new image