Bring the Docker and Docker Compose install pages to 5.x tags, first start behaviour, healthcheck, log rotation and optional variables

This commit is contained in:
Maurice
2026-10-24 23:18:18 +02:00
parent 9ffd5e5ffb
commit 0f88a74976
2 changed files with 34 additions and 10 deletions
+18 -5
View File
@@ -46,6 +46,14 @@ volumes:
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 `./storage-config.json` read-only at `/app/data/storage-config.json`. Uncomment it to provision file storage once on the first start. See [Admin-Storage](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:
@@ -64,25 +72,30 @@ Every other variable — `APP_URL`, the OIDC block, `FORCE_HTTPS`, `TRUST_PROXY`
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](Backups#restoring-on-a-new-install-before-setup)). 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](Environment-Variables).
## Image Tags
Three tag strategies are available:
Five tags are available:
| Tag | Example | Behavior |
|---|--------------------------|---|
| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions |
| Major version | `mauriceboe/trek:4` | Latest release pinned to that major version |
| Full version | `mauriceboe/trek:4.0.0` | Exact release; never changes |
| 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:
```yaml
image: mauriceboe/trek:4 # track major version 4
image: mauriceboe/trek:4.0.0 # pin to exact release
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
+16 -5
View File
@@ -39,14 +39,23 @@ See [Environment-Variables](Environment-Variables) for the full list.
| Tag | Example | Behavior |
|---|--------------------------|---|
| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions |
| Major version | `mauriceboe/trek:4` | Latest release pinned to that major version |
| 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: 4.x releases have no minor tag, so pin those by major or full version |
| Full version | `mauriceboe/trek:4.0.0` | Exact release; never changes |
| 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 |
Replace `mauriceboe/trek:latest` in the run command with your chosen tag to pin to a major version, a minor version or an exact release. Test builds of the next version are tagged `latest-pre`; see [Updating](Updating#image-tags).
Replace `mauriceboe/trek:latest` in the run command with your chosen tag to pin to a major version, a minor version or an exact release. See [Updating](Updating#image-tags) for how the tags behave.
Every image carries the standard `org.opencontainers.image.*` labels (title, version, source, documentation, licence), so an update tool such as Renovate links an image update to its release notes. `docker inspect mauriceboe/trek:latest --format '{{json .Config.Labels}}'` shows them.
## First Start
On the very first start with an empty database TREK creates an admin account. Without `ADMIN_EMAIL` and `ADMIN_PASSWORD` (both are needed, and they only apply on that first start) it uses `admin@trek.local` with a random password that is printed to the container log, so run `docker logs trek` and sign in with it. See [Quick-Start](Quick-Start).
When you start a newer image, TREK first copies the database to `data/pre-migrate-<schema>-<time>.db` before it applies any migration, so you can go back to the previous image if needed. See [Updating](Updating).
The in-app Help pages come from the image itself (`/app/wiki`), so they always match the version you run. You do not need to set `TREK_WIKI_DIR`.
## Volume Reference
| Volume | Container path | What lives there |
@@ -54,7 +63,9 @@ Every image carries the standard `org.opencontainers.image.*` labels (title, ver
| `./data` | `/app/data` | `travel.db` (SQLite database), `logs/trek.log`, `.jwt_secret`, `.encryption_key` |
| `./uploads` | `/app/uploads` | Uploaded files (photos, documents, covers, avatars) |
Both volumes must survive container replacement — they are your persistent state. Never remove them before pulling a new image.
Both volumes must survive container replacement — they are your persistent state. Never remove them before pulling a new image. Installed plugins also live under `data` by default (`TREK_PLUGINS_DIR` moves them), so they are covered as long as `data` persists.
You can optionally mount a `storage-config.json` read-only at `/app/data/storage-config.json` to set up file storage once on the first start. See [Admin-Storage](Admin-Storage).
### Named Volumes
@@ -96,7 +107,7 @@ docker logs trek
## Limitations of `docker run`
A bare `docker run` command has no built-in secret management and is harder to reproduce after a system reboot. For production, see [Install-Docker-Compose](Install-Docker-Compose), which adds security hardening (`read_only`, `cap_drop`, `cap_add`, `no-new-privileges`, `tmpfs`) and makes it easy to manage environment variables through a `.env` file.
A bare `docker run` command has no built-in secret management and is harder to reproduce after a system reboot. It also lacks the hardening of the compose file (`read_only`, `cap_drop`, `cap_add`, `no-new-privileges`, `tmpfs`) and does not rotate container logs, which the compose file limits to three files of 10 MB. For production, see [Install-Docker-Compose](Install-Docker-Compose), which also makes it easy to manage environment variables through a `.env` file.
## Next Steps