docs(db): document running TREK on Postgres, with compose and Helm support

- wiki/Database-Postgres.md: requirements (PostgreSQL 14 to 17, an empty
  database of its own, a role that is not a superuser, ICU), configuration
  and SSL, first boot, upgrades and the .pgdump copy, backups and restore,
  limitations (no SQLite to Postgres move yet, one replica), notes for
  Supabase, and the manual checklist still to run against it.
- docker-compose.postgres.yml: TREK beside a postgres:17 service.
- Helm: database.url (written into the chart's Secret) or
  database.existingSecret supplies TREK_DB_URL; replicas stay at one, now
  for the state TREK keeps in memory.
- Environment variables, backups, updating, troubleshooting, the Docker
  Compose and Helm install pages, the sidebar and the README point at it.
This commit is contained in:
Isaias Tavares
2026-11-02 17:23:09 -03:00
parent 526437926a
commit e0013bc077
15 changed files with 414 additions and 19 deletions
+4
View File
@@ -319,6 +319,10 @@ docker compose up -d
See [Install with Docker Compose](https://github.com/liketrek/TREK/wiki/Install-Docker-Compose)
for the full walkthrough.
TREK stores its data in SQLite by default. Set `TREK_DB_URL` to run it on a PostgreSQL 14 to 17 database instead. The
[`docker-compose.postgres.yml`](docker-compose.postgres.yml) example starts one beside TREK, and the
[Postgres guide](https://github.com/liketrek/TREK/wiki/Database-Postgres) covers the requirements and the backups.
<br />
<h2 id="helm-kubernetes">Helm (Kubernetes)</h2>
+1
View File
@@ -45,6 +45,7 @@ See `values.yaml` for more options.
- PVCs use the cluster's default StorageClass. Set `persistence.data.storageClassName` and/or `persistence.uploads.storageClassName` to bind a specific class.
- To use your own PVCs, set `persistence.data.existingClaim` and/or `persistence.uploads.existingClaim`. The other values for that volume (size, storageClassName, annotations) are then ignored.
- With `persistence.enabled: false`, the data and uploads volumes use an `emptyDir` — storage is ephemeral and lost on pod restart. Intended for testing only.
- `database.url` runs TREK on a PostgreSQL database instead of the SQLite file. The chart writes it into its Secret as `TREK_DB_URL`; `database.existingSecret` and `database.existingSecretKey` read it from a Secret you manage. Leave both empty for SQLite. Keep `replicas: 1` either way. See the wiki page `Database-Postgres`.
- `JWT_SECRET` is managed entirely by the server — auto-generated into the data PVC on first start and rotatable via the admin panel (Settings → Danger Zone). No Helm configuration needed.
- `ENCRYPTION_KEY` encrypts stored secrets (API keys, MFA, SMTP, OIDC) at rest. Recommended: set via `secretEnv.ENCRYPTION_KEY` or `existingSecret`. If left empty, the server falls back automatically: existing installs use `data/.jwt_secret` (no action needed on upgrade); fresh installs auto-generate a key persisted to the data PVC.
- Liveness and readiness probes are configurable under `probes`. Overrides are merged over the defaults, so `--set probes.liveness.initialDelaySeconds=60` keeps the `httpGet` handler. When switching to `exec` or `tcpSocket`, clear `httpGet` in the same override. Set `probes.liveness: null` to remove a probe.
+17 -4
View File
@@ -1,3 +1,6 @@
{{- if and .Values.database.url (not .Values.database.existingSecret) .Values.existingSecret }}
{{- fail "database.url is written into the chart's own Secret, which existingSecret replaces. Put TREK_DB_URL in your Secret and set database.existingSecret instead." }}
{{- end }}
apiVersion: apps/v1
kind: Deployment
metadata:
@@ -5,11 +8,13 @@ metadata:
labels:
app: {{ include "trek.name" . }}
spec:
# One replica. Its rate limits, pending codes, permission cache and WebSocket
# connections live in the process's memory, so a second pod would not share them. That
# holds with database.url (PostgreSQL) too; see updateStrategy in values.yaml.
replicas: 1
# TREK is a single-writer SQLite app on a ReadWriteOnce PVC, so the default
# RollingUpdate would start a second pod holding the same volume before the old one
# exits — a Multi-Attach deadlock, or two processes on one travel.db. Recreate tears
# the old pod down first. Keep it, see updateStrategy in values.yaml.
# The default RollingUpdate would start a second pod on the same ReadWriteOnce PVC
# before the old one exits: a Multi-Attach deadlock, or two processes on one travel.db.
# Recreate tears the old pod down first. Keep it, see updateStrategy in values.yaml.
strategy:
type: {{ .Values.updateStrategy | default "Recreate" }}
selector:
@@ -61,6 +66,14 @@ spec:
name: {{ default (printf "%s-secret" (include "trek.fullname" .)) .Values.existingSecret }}
key: {{ .Values.existingSecretKey | default "ENCRYPTION_KEY" }}
optional: true
{{- if or .Values.database.url .Values.database.existingSecret }}
# Required when set: a missing key stops the pod rather than starting it on SQLite.
- name: TREK_DB_URL
valueFrom:
secretKeyRef:
name: {{ default (printf "%s-secret" (include "trek.fullname" .)) .Values.database.existingSecret }}
key: {{ if .Values.database.existingSecret }}{{ .Values.database.existingSecretKey | default "TREK_DB_URL" }}{{ else }}TREK_DB_URL{{ end }}
{{- end }}
- name: ADMIN_EMAIL
valueFrom:
secretKeyRef:
+6
View File
@@ -8,6 +8,9 @@ metadata:
type: Opaque
data:
{{ .Values.existingSecretKey | default "ENCRYPTION_KEY" }}: {{ .Values.secretEnv.ENCRYPTION_KEY | b64enc | quote }}
{{- if .Values.database.url }}
TREK_DB_URL: {{ .Values.database.url | b64enc | quote }}
{{- end }}
{{- if .Values.secretEnv.ADMIN_EMAIL }}
ADMIN_EMAIL: {{ .Values.secretEnv.ADMIN_EMAIL | b64enc | quote }}
{{- end }}
@@ -65,6 +68,9 @@ stringData:
{{- else }}
{{ .Values.existingSecretKey | default "ENCRYPTION_KEY" }}: {{ randAlphaNum 32 | quote }}
{{- end }}
{{- if .Values.database.url }}
TREK_DB_URL: {{ .Values.database.url | quote }}
{{- end }}
{{- if .Values.secretEnv.ADMIN_EMAIL }}
ADMIN_EMAIL: {{ .Values.secretEnv.ADMIN_EMAIL | quote }}
{{- end }}
+20 -4
View File
@@ -4,10 +4,13 @@ image:
# tag: latest
pullPolicy: IfNotPresent
# Deployment update strategy. Keep Recreate: TREK is a single-writer SQLite app, and
# during a RollingUpdate the new pod migrates the database while the old one still
# writes to it. A ReadWriteMany volume does not make that safe; SQLite's WAL needs both
# processes on one host, which network filesystems do not provide.
# Deployment update strategy. Keep Recreate. The new pod migrates the database when it
# starts, and during a RollingUpdate it would do that while the old pod still writes to
# it. Recreate stops the old pod first. On SQLite two processes on one travel.db are
# unsafe, and a ReadWriteOnce volume cannot be attached to both pods at once.
# With database.url the database is PostgreSQL, but the reason for one replica stays: TREK
# keeps rate limits, pending codes, the permission cache and WebSocket connections in
# memory, so a second pod would not share them. Postgres does not make more replicas safe.
updateStrategy: Recreate
# Pod-level security context. fsGroup gives the node user (uid/gid 1000) group access
@@ -174,6 +177,19 @@ env:
# address is sent unless you set one here.
# Database. Empty (the default) keeps TREK on its SQLite file in the data volume. Set url to
# run TREK on a PostgreSQL database instead (see the wiki page Database-Postgres). The URL
# carries the password, so it is never a plain env value: with url, the chart writes it into
# its own Secret as TREK_DB_URL; with existingSecret, TREK reads TREK_DB_URL from that Secret
# under existingSecretKey and the chart writes nothing. existingSecret wins over url. The
# variable is required when either is set: a missing Secret key stops the pod instead of
# starting it on SQLite.
# url: "postgres://trek:<password>@postgres.example.internal:5432/trek?sslmode=require"
database:
url: ""
existingSecret: ""
existingSecretKey: TREK_DB_URL
# Secret environment variables stored in a Kubernetes Secret.
# JWT_SECRET is managed entirely by the server (auto-generated into the data PVC,
# rotatable via the admin panel) — it is not configured here.
+87
View File
@@ -0,0 +1,87 @@
# TREK on a Postgres database instead of the SQLite file. See the wiki page
# Database-Postgres for what this changes, the requirements and the backups.
#
# Set the database password in a .env file beside this file (or in the
# shell) before the first start:
# POSTGRES_PASSWORD=<a long random value>
# The password goes into TREK_DB_URL below, so keep it to URL-safe characters
# or percent-encode it. Without POSTGRES_PASSWORD the postgres image refuses to
# initialize its database, and TREK does not start.
services:
db:
image: postgres:17
container_name: trek-db
restart: unless-stopped
environment:
- POSTGRES_DB=${POSTGRES_DB:-trek}
- POSTGRES_USER=${POSTGRES_USER:-trek}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-}
security_opt:
- no-new-privileges:true
# No ports are published: only the trek service on the compose network reaches the database.
volumes:
- trek-pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
logging:
driver: json-file
options:
max-size: 10m
max-file: "3"
app:
image: mauriceboe/trek:latest
container_name: trek
depends_on:
db:
condition: service_healthy
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- CHOWN
- SETUID
- SETGID
# dumb-init runs as root and forwards SIGTERM to node, which runs as the
# node user; signalling another user's process needs KILL. See docker-compose.yml.
- KILL
tmpfs:
- /tmp:noexec,nosuid,size=128m
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- PORT=3000
- ENCRYPTION_KEY=${ENCRYPTION_KEY:-} # Recommended. Generate with: openssl rand -hex 32.
- TZ=${TZ:-UTC}
- LOG_LEVEL=${LOG_LEVEL:-info}
- ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-}
# The database URL. Its host is the service name above; sslmode=disable is
# right on the compose network. Use sslmode=verify-full with sslrootcert=
# for a database reached over a network you do not control.
- TREK_DB_URL=postgres://${POSTGRES_USER:-trek}:${POSTGRES_PASSWORD:-}@db:5432/${POSTGRES_DB:-trek}?sslmode=disable
# Scale-out is not supported: keep one trek container (see Database-Postgres).
volumes:
- ./data:/app/data
- ./uploads:/app/uploads
restart: unless-stopped
logging:
driver: json-file
options:
max-size: 10m
max-file: "3"
healthcheck:
test: ["CMD-SHELL", "wget -qO- http://localhost:$${PORT:-3000}/api/health || exit 1"]
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
volumes:
trek-pgdata:
+1 -1
View File
@@ -56,7 +56,7 @@ DEMO_MODE=false # Demo mode: resets data hourly
# TREK_DB_PG_BIN_DIR=/usr/lib/postgresql/17/bin # The directory holding pg_dump, pg_restore and psql, which back up and restore a Postgres database. Unset, TREK looks in /usr/lib/postgresql/<17..14>/bin, /usr/local/bin and /usr/bin (the Docker image installs the version 17 tools, which cannot dump a newer server). Unused on SQLite.
# TREK_DB_POOL_MAX=10 # Most connections TREK opens to the Postgres database (1 to 100). Unused on SQLite. (default: 10)
# TREK_DB_JOURNAL_MODE=WAL # SQLite journal mode (DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF). WAL is fastest and the right choice on local disk. Set DELETE if the data directory lives on network storage (Azure App Service, an SMB/NFS volume on a NAS) — WAL coordinates writers through a shared-memory file that those filesystems do not implement reliably. The mode is stored inside the database file, so it survives a restart; changing this applies on the next boot.
# TREK_DB_PRE_MIGRATE_SNAPSHOT=true # Copy the database to data/pre-migrate-<schema>-<time>.db before a startup migrates it, so the previous image can run on the copy again. A copy that cannot be written stops the startup; false migrates without one.
# TREK_DB_PRE_MIGRATE_SNAPSHOT=true # Copy the database to data/pre-migrate-<schema>-<time>.db (a .pgdump made with pg_dump on Postgres) before a startup migrates it, so the previous image can run on the copy again. A copy that cannot be written stops the startup; false migrates without one.
# TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP=3 # How many pre-migrate copies to keep, newest first (1 to 100). (default: 3)
# TREK_DB_SYNCHRONOUS=NORMAL # How hard SQLite flushes to disk (OFF, NORMAL, FULL, EXTRA). Defaults to NORMAL under WAL and FULL under any other journal mode — leave it alone unless you know why you want otherwise. Both variables fall back to their default (with a warning in the log) if the value is not a mode SQLite knows.
+5 -5
View File
@@ -1,6 +1,6 @@
# Backups
TREK stores all data in a single SQLite database (`travel.db`) plus an `uploads/` directory of attachments, cover photos, and avatars, by default; storage backends and replication are configured in [[Admin: Storage|Admin-Storage]]. The Backup panel lets you create, download, restore, and schedule backups of both.
TREK stores all data in a single SQLite database (`travel.db`) plus an `uploads/` directory of attachments, cover photos, and avatars, by default. On a [PostgreSQL database](Database-Postgres) (`TREK_DB_URL` set) the database is `travel.pgdump` instead. Storage backends and replication are configured in [[Admin: Storage|Admin-Storage]]. The Backup panel lets you create, download, restore, and schedule backups of both.
## Where to find it
@@ -14,7 +14,7 @@ A backup is a ZIP archive with these entries:
| Entry | Contents |
|---|---|
| `travel.db` | The full SQLite database, as a consistent snapshot taken while TREK keeps running (writes during the backup cannot tear it) |
| `travel.db` | The full SQLite database, as a consistent snapshot taken while TREK keeps running (writes during the backup cannot tear it). On PostgreSQL this entry is `travel.pgdump` instead: a `pg_dump` custom-format file, taken from one consistent snapshot of the database. |
| `uploads/` | All uploaded attachments, covers, and avatars (default location, see [Admin: Storage](Admin-Storage)) |
| `plugins-data/` | Each installed plugin's own database + files (present only if plugins are installed) |
| `plugins-code/` | The installed plugin code, so a restore is self-contained (dev-linked plugins are skipped) |
@@ -38,13 +38,13 @@ You can restore from:
A second limit caps the **decompressed** size of a restore archive at 5 GB by default (`BACKUP_MAX_DECOMPRESSED_MB`). It applies to both routes (a stored backup as well as an uploaded ZIP) and a restore that exceeds it is refused with `Backup exceeds the maximum decompressed size.` Raise it if your own backups legitimately grow past the default, otherwise they become unrestorable.
Before restoring, TREK runs integrity checks on the uploaded database:
Before restoring, TREK runs integrity checks on the uploaded database. On PostgreSQL the first two are replaced by the checks in [Database: Postgres](Database-Postgres#backups-and-restore).
1. **SQLite `PRAGMA integrity_check`**: verifies the database file is not corrupt.
2. **Required tables present**: confirms the file contains `users`, `trips`, `trip_members`, `places`, and `days`. Files missing any of these are rejected as not being a valid TREK backup.
3. **Not from a newer TREK**: a backup whose database a newer release migrated is refused with `This backup was made by a newer TREK version. Update TREK before restoring it.` Restoring it would leave this version unable to start.
The database being replaced is kept as `pre-restore-<time>.db` next to it (in `data/` on a standard install), so a restore of the wrong archive can be undone by hand. Delete these copies once you no longer need them.
The database being replaced is kept as `pre-restore-<time>.db` next to it (in `data/` on a standard install), so a restore of the wrong archive can be undone by hand. On PostgreSQL the copy is `pre-restore-<time>.pgdump`. Delete these copies once you no longer need them.
The sessions signed in when the restore starts stay signed in, yours included: they are carried into the restored database for every account it holds under the same id and email. An account whose password differs in the backup still has to sign in again, and a session for an account the backup does not have ends with the restore.
@@ -98,7 +98,7 @@ The phone admin has the same lists and settings in its **Backup** section.
Always create a manual backup before updating. See [Updating](Updating).
TREK also copies the database by itself right before a startup migrates it, to `data/pre-migrate-<schema>-<time>.db`, and keeps the newest three. That copy is what an older image can be started on again if you have to roll an update back. It holds the database only, never uploads, so it does not replace a backup. See [Updating](Updating#database-migrations).
TREK also copies the database by itself right before a startup migrates it, to `data/pre-migrate-<schema>-<time>.db` (`.pgdump` on PostgreSQL), and keeps the newest three. That copy is what an older image can be started on again if you have to roll an update back. It holds the database only, never uploads, so it does not replace a backup. See [Updating](Updating#database-migrations).
## Audit log
+147
View File
@@ -0,0 +1,147 @@
# Database: Postgres
By default TREK keeps all data in one SQLite file, `travel.db`, in the data directory. Setting `TREK_DB_URL` runs TREK on a PostgreSQL database instead. Without that variable nothing changes, and every page of this wiki that describes `travel.db` still applies to an install on SQLite.
> **Status:** Postgres support is new. It has been checked end to end against PostgreSQL 17 in Docker (first boot, sign-in, trips, backup and restore, the copy before a migration, `RESTORE_FROM_BACKUP`). The checks against Supabase are still pending; see [Manual verification checklist](#manual-verification-checklist-pending) below.
## When to use it
Use Postgres when you already run a PostgreSQL server and want TREK's data there, for example to back it up or monitor it with the tools you use for other databases. A single TREK container on a host with a local disk does not need it.
Postgres does not make TREK scale out. TREK still runs as one process. See [Limitations](#limitations).
## Requirements
- **PostgreSQL 14 to 17.**
- **An empty database dedicated to TREK.** TREK creates its schema in an empty database. It refuses a database that holds tables it did not create, and a restore replaces everything in the schema it loads into. Do not share the database with another application.
- **A role that is not a superuser,** which owns the database or can create objects in its schema. A backup archive is a SQL script run by this role during a restore, so a role with fewer privileges limits what a crafted archive can do.
- **ICU support in the server.** The schema creates the collation `nocase` with `provider = icu`, so the server must be built with ICU. The official `postgres` images include it.
- **PostgreSQL client tools** (`pg_dump`, `pg_restore`, `psql`) for backups, restores and the copy TREK takes before a migration. The Docker image installs the version 17 client. The client cannot dump a server newer than 17, so a PostgreSQL 18 server needs a client of the same major version, installed on the host or in a custom image, and pointed at with `TREK_DB_PG_BIN_DIR`. See [Configuration](#configuration).
- **Client tool versions that carry the CVE-2025-8714 fix.** A restore refuses `pg_restore` or `psql` older than 17.6, 16.10, 15.14 or 14.19.
## Configuration
| Variable | What it does | Default |
|---|---|---|
| `TREK_DB_URL` | Connection URL, `postgres://user:password@host:5432/database` (or `postgresql://`). Setting it selects Postgres. | unset (SQLite) |
| `TREK_DB_POOL_MAX` | Most connections TREK opens to the database, from 1 to 100. The pool sets no minimum, so idle connections can close. | `10` |
| `TREK_DB_PG_BIN_DIR` | Directory holding `pg_dump`, `pg_restore` and `psql`. | see below |
Percent-encode the user name and password inside the URL if they contain characters such as `@`, `:`, `/` or `#`.
### Combining with SQLite settings
`TREK_DB_URL` cannot be combined with `TREK_DB_FILE`, `TREK_DB_JOURNAL_MODE` or `TREK_DB_SYNCHRONOUS`. TREK refuses to start when both are set, because it would not know which database was meant. Unset the SQLite variables. `TREK_DB_PRE_MIGRATE_SNAPSHOT` and `TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP` still apply, but the copy they control is a `.pgdump` file. See [Upgrades](#upgrades).
### SSL
The `sslmode` parameter in the URL selects how the connection is secured:
| `sslmode` | Effect |
|---|---|
| `disable` | No SSL. |
| `require`, `verify-ca`, `verify-full` | SSL, with the server certificate verified. |
| anything else (for example `prefer`, `allow`, `no-verify`, or a misspelling) | TREK refuses to start. |
Without `sslmode`, the connection pool uses no SSL. The client tools use the libpq default for an unset `sslmode`, so set `sslmode` explicitly. For the backup and restore tools, every mode other than `disable` verifies the server, including its host name.
`sslrootcert=` names the file holding the certificate authority that signs the server's certificate. It is needed when the server uses a certificate from a private CA, and it is valid only together with one of the verifying modes. The file must be readable inside the container, so mount it into the container and point the URL at the path inside the container. Without `sslrootcert`, the system's trusted certificate authorities are used.
### Where the client tools are found
TREK runs the tools by their absolute path. It does not search `PATH`. When `TREK_DB_PG_BIN_DIR` is unset, TREK looks in these directories, in order, and uses the first one that holds the tool:
1. `/usr/lib/postgresql/17/bin`
2. `/usr/lib/postgresql/16/bin`
3. `/usr/lib/postgresql/15/bin`
4. `/usr/lib/postgresql/14/bin`
5. `/usr/local/bin`
6. `/usr/bin`
The password is passed to the tools in the `PGPASSWORD` environment variable of their process. It never appears on a command line, where other processes could read it.
### Compose example
[`docker-compose.postgres.yml`](https://github.com/liketrek/TREK/blob/main/docker-compose.postgres.yml) runs a `postgres:17` service beside TREK, on a named volume, with the TREK container waiting for the database to pass its health check. Set `POSTGRES_PASSWORD` in a `.env` file beside it before the first start. See [Install: Docker Compose](Install-Docker-Compose#running-on-postgres).
## First boot
On the first start against an empty database, TREK:
1. Creates the schema from its baseline and records every migration the baseline covers as applied, in one transaction.
2. Applies any migrations after the baseline.
3. Seeds its default data and creates the admin account, from `ADMIN_EMAIL` and `ADMIN_PASSWORD` when set. Otherwise it prints a random password to the log.
A database that holds tables TREK did not create, and no TREK migration history, is refused. TREK names a few of the tables and writes nothing to the database. Point `TREK_DB_URL` at an empty database.
A database migrated by a newer TREK is refused, and the log says to run that version again or to restore a backup taken with this one.
**Start one TREK process for the first boot and for every upgrade.** Two processes that start at the same time on the same new database are not coordinated. The second one fails its boot, because the first one's schema transaction wins. Once the database is up to date and running, a single container is the supported setup. See [Limitations](#limitations).
### Moving an existing SQLite install
This first Postgres release has no tool that copies a SQLite install into Postgres. A SQLite backup cannot be restored into a Postgres database, and a Postgres backup cannot be restored into SQLite. Moving an existing install to Postgres means starting a new install on Postgres and recreating the data there, or keeping the SQLite install running.
## Upgrades
On a startup that has pending migrations, TREK writes a copy of the database before it migrates anything:
- The copy is a `pg_dump` custom-format file, `data/pre-migrate-<last migration>-<time>.pgdump`, next to the data the container keeps. The log prints the path.
- The newest `TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP` copies are kept (3 by default).
- If the copy cannot be written, for example because a client tool is missing or the disk is full, TREK refuses to migrate and does not start. Fix the cause, or set `TREK_DB_PRE_MIGRATE_SNAPSHOT=false` to migrate without a copy.
- A restart with nothing pending, and a first start on an empty database, write no copy.
The copy is a safety net for an update. It does not replace a backup, and it does not hold uploads. To go back to the previous image, follow [Updating: Rolling back a Postgres update](Updating#rolling-back-a-postgres-update).
## Backups and restore
A Postgres install produces the same backup archive as a SQLite install, with one difference: the database is stored as `travel.pgdump`, a `pg_dump` custom-format file, instead of `travel.db`. The uploads, plugin data and the encryption key are in the archive as before. See [Backups](Backups).
Restoring a backup on Postgres follows these rules:
- **The current database is replaced.** TREK first keeps a copy of it as `data/pre-restore-<time>.pgdump`. `pg_restore` then turns the archive's dump into a SQL script, and `psql` clears the current schema, which drops its tables, views, sequences, functions, types and collations, and runs the script. Both steps run in one transaction, so a restore that fails leaves the database as it was.
- **TREK checks the archive before it replaces anything.** The archive must hold a Postgres dump, not a SQLite file. The dump must carry TREK's migration history, and it must not come from a newer TREK. TREK refuses the restore with a message saying which check failed.
- **The client tools must be recent enough.** The restore refuses `pg_restore` or `psql` older than 17.6, 16.10, 15.14 or 14.19.
`RESTORE_FROM_BACKUP` works on Postgres too. On the first start, TREK loads the archive's dump into the database when that database holds no tables. When the database already has tables, the variable is ignored and TREK logs a warning. See [Backups: Restoring on a new install, before setup](Backups#restoring-on-a-new-install-before-setup).
## Limitations
- **No migration from SQLite to Postgres** in this first release. Start a new install on Postgres, or keep the SQLite install.
- **No more than one TREK replica.** TREK keeps state in memory: rate limits, pending one-time codes, the permission cache and the WebSocket connections. Each process has its own copy, so two replicas would disagree with each other. Keep `replicas: 1` in the Helm chart and one `trek` container. Postgres does not change that.
- **Two processes booting on one database at once are not coordinated.** Start one process for the first boot and for each upgrade, then continue with one.
- **Client tools for server version 18 and later.** The Docker image's client is version 17, which cannot dump a newer server. Point `TREK_DB_PG_BIN_DIR` at a matching client.
- **Writes are serialized.** TREK takes a database-wide advisory lock for each write transaction, as the SQLite engine does with its single writer. Heavy concurrent writes wait on that lock.
## Supabase
Supabase runs PostgreSQL and can host TREK's database. These notes describe the connection setup. They have not been tested against a Supabase project; see the checklist below.
- **Use the direct connection or the session pooler.** The direct connection uses port 5432. Its host resolves to IPv6 unless the project has the IPv4 add-on, so on a network without IPv6 use the session pooler, which also listens on port 5432 on its own host.
- **Do not use the transaction pooler** (port 6543) for TREK. `pg_dump` and `psql` need a session that lasts for the whole run, and the transaction pooler does not give one.
- **Use `sslmode=require`.** If Supabase's certificate is not trusted by the system certificate authorities in the TREK container, mount its CA file and add `sslrootcert=` with the path inside the container.
- **The role must be able to create the collation.** The schema creates the `nocase` collation. The `postgres` role that Supabase gives the project is expected to have that right. This has not been checked against a project.
- **The database's `public` schema must hold no tables** when TREK first starts, because TREK refuses a database with tables it did not create.
## Manual verification checklist (pending)
This checklist has not been run against Supabase yet. It is the test to complete before a Supabase install relies on this page. Run it once with the direct connection and once with the session pooler, against a throwaway database.
1. Create an empty database and a non-superuser role that owns it. Set `TREK_DB_URL` with `sslmode=require` for Supabase, or with the server's own setting otherwise.
2. Start one TREK process. Confirm the log reports the Postgres engine, the schema is created, and the admin account exists.
3. Sign in, create a trip, and confirm it appears after a page reload.
4. Create a backup from the Backup tab. Confirm the archive holds `travel.pgdump` and no `travel.db`.
5. Restore that backup from the Backup tab. Confirm the trip is still there, and that `data/pre-restore-<time>.pgdump` exists.
6. Stop and start TREK. Confirm the data is unchanged and no migration runs.
7. Upgrade: start an older image on a database, then the newer image. Confirm `data/pre-migrate-<last migration>-<time>.pgdump` appears, and that the migration runs.
8. Roll back with the copy, as described in [Updating](Updating#rolling-back-a-postgres-update), and confirm the older image starts on it.
9. Record the server version, the client tool versions, and any error text that differs from this page.
## See also
- [Environment Variables](Environment-Variables)
- [Backups](Backups)
- [Updating](Updating)
- [Troubleshooting](Troubleshooting)
- [Install: Docker Compose](Install-Docker-Compose)
- [Install: Helm](Install-Helm)
+7 -2
View File
@@ -475,12 +475,17 @@ through environment variables. `TREK_PLACE_PHOTO_DIR` below is unaffected.
| `BACKUP_UPLOAD_LIMIT_MB` | Maximum **compressed** size (in MB) of a restore-backup archive that may be uploaded. Raise it if your backups (which include the `uploads/` directory) exceed the default. Non-positive or invalid values abort startup. | `500` |
| `RESTORE_FROM_BACKUP` | Path to a backup ZIP to restore on the **first** start, before any setup. Only acts while no database exists; afterwards it is ignored with a warning. A backup that fails the restore checks stops the start. See [Backups](Backups#restoring-on-a-new-install-before-setup). | none |
| `BACKUP_MAX_DECOMPRESSED_MB` | Maximum **decompressed** size (in MB) of a restore-backup archive — the zip-bomb guard. Independent of `BACKUP_UPLOAD_LIMIT_MB` and enforced on both restore paths, so a restore that fits the upload cap can still be refused with `Backup exceeds the maximum decompressed size.` Raise both when restoring a very large instance. | `5120` (5 GB) |
| `TREK_DB_FILE` | Explicit path of the database file. Unset, TREK uses `travel.db` in the data directory. | unset |
| `TREK_DB_URL` | Run TREK on a PostgreSQL database instead of the SQLite file: `postgres://user:password@host:5432/database` (or `postgresql://`). Needs PostgreSQL 14 to 17 and an empty database of its own. Percent-encode special characters in the password. See [Database: Postgres](Database-Postgres). | unset (SQLite) |
| `TREK_DB_POOL_MAX` | Most connections TREK opens to the PostgreSQL database, from 1 to 100. Unused on SQLite. | `10` |
| `TREK_DB_PG_BIN_DIR` | Directory holding `pg_dump`, `pg_restore` and `psql`, which back up and restore a PostgreSQL database. Unset, TREK looks in `/usr/lib/postgresql/17` to `14` (`bin`), `/usr/local/bin` and `/usr/bin`. Unused on SQLite. See [Database: Postgres](Database-Postgres#where-the-client-tools-are-found). | unset |
| `TREK_DB_FILE` | Explicit path of the SQLite database file. Unset, TREK uses `travel.db` in the data directory. Not used with `TREK_DB_URL`. | unset |
| `TREK_DB_JOURNAL_MODE` | SQLite [journal mode](https://sqlite.org/pragma.html#pragma_journal_mode): `DELETE`, `TRUNCATE`, `PERSIST`, `MEMORY`, `WAL` or `OFF`. Set `DELETE` when the data directory lives on network storage — see below. Values SQLite doesn't know log a warning and fall back. | `WAL` |
| `TREK_DB_PRE_MIGRATE_SNAPSHOT` | Copy the database to `pre-migrate-<schema>-<time>.db` next to it before a startup applies pending migrations, so the previous image can be started on that copy again. If the copy cannot be written the startup refuses rather than migrate without one. Set `false` only to get past that when you cannot free space and have a backup of your own. See [Updating](Updating#database-migrations). | `true` |
| `TREK_DB_PRE_MIGRATE_SNAPSHOT` | Copy the database to `pre-migrate-<schema>-<time>.db` next to it before a startup applies pending migrations, so the previous image can be started on that copy again. On PostgreSQL the copy is a `pg_dump` file, `pre-migrate-<schema>-<time>.pgdump`, and needs the client tools (see `TREK_DB_PG_BIN_DIR`). If the copy cannot be written the startup refuses rather than migrate without one. Set `false` only to get past that when you cannot free space and have a backup of your own. See [Updating](Updating#database-migrations). | `true` |
| `TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP` | How many of those copies stay in the data directory, newest first (1 to 100). | `3` |
| `TREK_DB_SYNCHRONOUS` | SQLite [synchronous](https://sqlite.org/pragma.html#pragma_synchronous) level: `OFF`, `NORMAL`, `FULL` or `EXTRA`. The default follows the journal mode — `NORMAL` under WAL (what SQLite itself uses there), `FULL` otherwise, because a rollback journal at `NORMAL` can lose committed transactions on a power cut. | `NORMAL` / `FULL` |
With `TREK_DB_URL` set, the SQLite variables (`TREK_DB_FILE`, `TREK_DB_JOURNAL_MODE`, `TREK_DB_SYNCHRONOUS`) do not apply, and setting any of them alongside `TREK_DB_URL` stops the startup. The pre-migration copy settings (`TREK_DB_PRE_MIGRATE_SNAPSHOT` and `TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP`) apply to both engines. The [Database: Postgres](Database-Postgres) page covers the connection, SSL and backups on PostgreSQL.
### Running the database on network storage
WAL is the right mode on a local disk and stays the default. It coordinates readers and writers through a shared-memory
+16 -1
View File
@@ -24,7 +24,7 @@ The compose file ships with several hardening options enabled by default:
| Host path | Container path | Contents |
|---|---|---|
| `./data` | `/app/data` | SQLite database, logs, `.jwt_secret`, `.encryption_key` |
| `./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
@@ -116,6 +116,21 @@ This compose file is designed for deployments where a reverse proxy (nginx, Cadd
See [Reverse-Proxy](Reverse-Proxy) for complete proxy configuration examples.
## Running on Postgres
[`docker-compose.postgres.yml`](https://github.com/liketrek/TREK/blob/main/docker-compose.postgres.yml) runs TREK beside a `postgres:17` service instead of the SQLite file. Its `db` service keeps the database in a named volume and publishes no port, and the `trek` service waits for the database's health check before it starts.
Put a password in a `.env` file beside the compose file, then start it:
```bash
echo 'POSTGRES_PASSWORD=<a long random value>' > .env
docker compose -f docker-compose.postgres.yml up -d
```
The password goes into `TREK_DB_URL`, so use URL-safe characters or percent-encode it. Without `POSTGRES_PASSWORD` the database does not initialize and TREK does not start. 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](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](Environment-Variables) — full variable reference
+28 -1
View File
@@ -177,6 +177,33 @@ Every value the chart writes into its Secret is quoted, so a password such as `1
> **Note:** Without `UNSPLASH_ACCESS_KEY` the server queries Unsplash's unauthenticated endpoint, which many datacenter and VPS IP ranges — including a lot of Kubernetes clusters — are blocked or rate-limited on. Trip-cover and place-image search then fail with **"Unsplash search unavailable"**. A free Access Key switches the server to Unsplash's authenticated API (`api.unsplash.com`), which is not subject to that block. The key can also be set in **Admin → Settings → API Keys**; this value takes priority over that one. See [Environment-Variables](Environment-Variables#image-search-unsplash).
### Running on Postgres
To run TREK on a PostgreSQL database, set `database.url`. The connection URL carries the password, so the chart writes it into its own Secret as `TREK_DB_URL` rather than into the ConfigMap:
```yaml
database:
url: "postgres://trek:<password>@postgres.example.internal:5432/trek?sslmode=require"
```
To keep the URL out of your values file, create a Secret yourself and point the chart at it. The key holds the same URL:
```bash
kubectl create secret generic trek-db --from-literal=TREK_DB_URL='postgres://trek:<password>@postgres.example.internal:5432/trek?sslmode=require'
```
```yaml
database:
existingSecret: trek-db
existingSecretKey: TREK_DB_URL # the default
```
The chart then reads `TREK_DB_URL` from that Secret. If the key is missing, the pod does not start. It does not fall back to SQLite. The chart refuses to render when `database.url` and the top-level `existingSecret` are both set, because the chart's own Secret, which holds the URL, is not created in that case. Use `database.existingSecret` instead.
The database must be empty and dedicated to TREK, with a role that is not a superuser. The data and uploads volumes are still needed: they hold the data directory, the uploads and the copies TREK takes before migrating. The PostgreSQL requirements, the SSL settings (`sslmode`, `sslrootcert` with a CA file mounted into the pod) and the backups are on [Database: Postgres](Database-Postgres).
Keep `replicas: 1` on Postgres too. TREK keeps rate limits, pending codes, the permission cache and WebSocket connections in memory, so a second pod would not share them. See [Limitations](Database-Postgres#limitations).
### Persistent Storage
The data PVC holds the database, the plugins you install and the automatic `pre-migrate-<schema>-<time>.db` copy TREK writes before an upgrade migrates the database, so the previous image can run on that copy again. See [Updating](Updating).
@@ -328,7 +355,7 @@ Timeout fields are Standard Channel in Gateway API v1.2, though controller suppo
## Upgrade
The Deployment uses the `Recreate` update strategy (`updateStrategy: Recreate`): the old pod stops before the new one starts. TREK is a single-writer SQLite application, and during a rolling update the new pod would migrate the database while the old one still writes to it. A ReadWriteMany volume does not make that safe, so leave the strategy as it is and keep one replica.
The Deployment uses the `Recreate` update strategy (`updateStrategy: Recreate`): the old pod stops before the new one starts. The new pod migrates the database when it starts, and during a rolling update it would do that while the old pod still writes to it. On SQLite that is unsafe, and a ReadWriteMany volume does not make it safe either. On Postgres the database is no longer a file, but the strategy and the single replica stay for the in-memory state described above. Leave the strategy as it is and keep one replica.
The in-app Help pages come from the image (`/app/wiki`), so they match the version you upgrade to.
+56
View File
@@ -645,3 +645,59 @@ See [Notifications](Notifications#web-push) for the details.
**Cause:** The server kept refusing a queued change (after eight attempts it counts as failed), or an edit you made offline collided with a newer one on the server.
**Fix:** The status pill at the bottom of the window reads **Failed to sync: N** or **Conflicts: N**. Open **Settings → Offline**. Under **Failed changes**, use **Try again** or **Discard** on each item. Under conflicts, choose **Keep mine** or **Keep theirs**. If the local copy itself looks wrong, **Clear cache** empties it and the next sync downloads it again. Unsynced changes are kept when a trip is cleared from the device. See [Offline-Mode-and-PWA](Offline-Mode-and-PWA).
---
## Postgres: TREK refuses to start because the database holds tables
**Cause:** `TREK_DB_URL` points at a database that already has tables, and none of them is TREK's migration history. TREK creates its schema only in an empty database, and it does not adopt tables another application made. The log reads `[DB] Refusing to boot: the database holds N table(s) (...) but no TREK migration history.` Nothing was written to the database.
**Fix:** Create a new, empty database for TREK, or point `TREK_DB_URL` at the one TREK already migrated. If this database is the wrong one, check the URL. See [Database-Postgres](Database-Postgres#first-boot).
---
## Postgres: TREK refuses to start because a copy before migrating could not be written
**Cause:** Before it applies pending migrations, TREK writes a `pg_dump` copy to `data/pre-migrate-<schema>-<time>.pgdump`. If `pg_dump` is not installed where TREK looks, or the data directory is full or read-only, the copy fails and TREK refuses to migrate. The log says `could not write a copy of the database ... Nothing was migrated.`
**Fix:** Install the PostgreSQL client tools (the Docker image has them) or set `TREK_DB_PG_BIN_DIR` to the directory that holds `pg_dump`. Free disk space or fix the permissions on `data/`, then start again. To migrate without a copy, set `TREK_DB_PRE_MIGRATE_SNAPSHOT=false`, but only when you have a backup of your own. See [Updating](Updating#database-migrations).
---
## Postgres: "pg_dump was not found" when backing up or restoring
**Cause:** The backup, restore or pre-migration copy runs `pg_dump`, `pg_restore` or `psql` by its absolute path. None of them is in the directories TREK searches (`/usr/lib/postgresql/17` down to `14`, `/usr/local/bin`, `/usr/bin`), and `PATH` is not searched.
**Fix:** Install the `postgresql-client` package, or set `TREK_DB_PG_BIN_DIR` to the directory that holds the three tools. The Docker image already includes the version 17 client. See [Database-Postgres](Database-Postgres#where-the-client-tools-are-found).
---
## Postgres: a backup or restore fails with "server version mismatch" or a version error
**Cause:** Two different problems produce messages about versions. `pg_dump` from version 17 cannot dump a server running version 18 or later, and fails with `aborting because of server version mismatch`. A restore also refuses a `pg_restore` or `psql` older than 17.6, 16.10, 15.14 or 14.19, because those versions cannot restore a dump safely (CVE-2025-8714). The error names the version it found.
**Fix:** For a newer server, point `TREK_DB_PG_BIN_DIR` at client tools of the same major version as the server. For an old client, install a newer `postgresql-client` package, or use a newer image. The Docker image's client is version 17, so it works with servers 14 to 17.
---
## Postgres: TREK refuses to start because of the sslmode in TREK_DB_URL
**Cause:** The `sslmode` parameter is not one TREK accepts. TREK accepts `disable`, `require`, `verify-ca` and `verify-full`. A value such as `prefer`, `allow` or `no-verify`, or a misspelling, would connect without verifying the server, so TREK refuses to start. A `sslrootcert` that names a file the container cannot read stops the start the same way.
**Fix:** Set `sslmode` to one of the four accepted values, and mount the CA file and point `sslrootcert` at its path inside the container. See [Database-Postgres](Database-Postgres#ssl).
---
## Postgres: TREK refuses to start because TREK_DB_URL is set with a SQLite variable
**Cause:** `TREK_DB_URL` is set together with `TREK_DB_FILE`, `TREK_DB_JOURNAL_MODE` or `TREK_DB_SYNCHRONOUS`. TREK cannot tell which database those variables mean, so it refuses to start.
**Fix:** Unset the SQLite variables. See [Environment-Variables](Environment-Variables).
---
## Postgres: a restore refuses the archive
**Cause:** The archive is not a Postgres backup, or it cannot be loaded here. The message says which: `This backup holds a SQLite database, which cannot be restored into a Postgres database.` (a backup from a SQLite install), `The uploaded dump holds no TREK migration history.` (a dump that is not from TREK), or `This backup was made by a newer TREK version.` A SQLite backup cannot be restored into PostgreSQL, and a PostgreSQL backup cannot be restored into SQLite.
**Fix:** Restore a backup taken on the same engine. For a newer backup, update TREK first. The database being replaced is kept as `data/pre-restore-<time>.pgdump` before the load starts. An archive that is refused is not loaded, so the database itself is unchanged. See [Backups](Backups#restoring-a-backup).
+18 -1
View File
@@ -84,7 +84,7 @@ TREK runs any pending database migrations automatically at startup. No manual mi
Migrations only go forward, so going back to an older image means going back to a copy of the database from before the update. Images from 5.0 on refuse to start on a database a newer TREK has migrated. Images from 4.3.x and earlier do not check this: they start on the newer database without a warning, so restore the copy before you start one of them.
TREK takes that copy itself. Right before a startup applies pending migrations, it writes the database to `data/pre-migrate-<schema>-<time>.db` (next to `travel.db`, or next to the file `TREK_DB_FILE` names) and logs the path. `<schema>` names what the copy holds: `legacy-244` for a 4.3.3 install, or the last migration's number for a newer one. The newest three are kept (`TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP`). A restart with nothing to migrate and a brand-new install take no copy.
TREK takes that copy itself. Right before a startup applies pending migrations, it writes the database to `data/pre-migrate-<schema>-<time>.db` (next to `travel.db`, or next to the file `TREK_DB_FILE` names) and logs the path. On PostgreSQL it writes a `.pgdump` file instead; see [Rolling back a Postgres update](#rolling-back-a-postgres-update). `<schema>` names what the copy holds: `legacy-244` for a 4.3.3 install, or the last migration's number for a newer one. The newest three are kept (`TREK_DB_PRE_MIGRATE_SNAPSHOT_KEEP`). A restart with nothing to migrate and a brand-new install take no copy.
If the copy cannot be written (the disk is full, or the data directory is read-only), TREK does not migrate and refuses to start, with a message naming the path. Free some space and start again. If you cannot, and you have a backup of your own, `TREK_DB_PRE_MIGRATE_SNAPSHOT=false` starts without the copy.
@@ -96,6 +96,23 @@ To go back to the previous image after an update:
An image from 5.0 on that refuses a newer database names the copy it can run, if one is in the data directory. An image from 4.3.x or earlier neither refuses nor points at the copy, so for those, steps 1 to 3 are the only way back. Uploads are not part of this copy; they are not changed by migrations. The copy is a safety net for the update, not a backup: keep taking backups as described in [Backups](Backups).
### Rolling back a Postgres update
On a [PostgreSQL database](Database-Postgres) the copy TREK takes before a migration is `data/pre-migrate-<schema>-<time>.pgdump`, a `pg_dump` custom-format file, and the procedure is different from the SQLite one above. The copy holds the database only. Anything written after it was taken is lost when you roll back, and the uploads are not affected.
1. Stop TREK.
2. Empty the database: drop it and create it again with the same owner, or drop the tables in its schema. `pg_restore` cannot load into a database that still holds the migrated tables.
3. Load the copy with the client tools of a version that carries the CVE-2025-8714 fix (17.6, 16.10, 15.14 or 14.19 at least):
```bash
pg_restore --no-owner --no-privileges --single-transaction -d "postgres://user:password@host:5432/trek?sslmode=require" data/pre-migrate-<schema>-<time>.pgdump
```
Use the same connection URL as `TREK_DB_URL`. The password can also come from the `PGPASSWORD` environment variable, which keeps it out of the command line.
4. Start the previous image with the same `TREK_DB_URL`.
A TREK image without PostgreSQL support cannot read this database at all. It would start on a new SQLite file instead. An image from 5.0 on that refuses a newer database names the copy it can run, if one is in the data directory.
## After the Update
The first time a user opens TREK on the desktop after an update, a notice headed **Update installed** opens on top of the app: three cards with the headline features of that release, a note from the maintainer, a **Release notes** link to the full notes on GitHub, and links for supporting the project. Every user sees it once per version. Closing it keeps it closed on that version, and the next update brings it back, a patch release included. The phone does not show it.
+1
View File
@@ -125,6 +125,7 @@
- [[Audit Log|Audit-Log]]
## Operations
- [[Database: Postgres|Database-Postgres]]
- [[Demo Mode|Demo-Mode]]
- [[Encryption Key Rotation|Encryption-Key-Rotation]]
- [[Internal Network Access|Internal-Network-Access]]