diff --git a/wiki/Encryption-Key-Rotation.md b/wiki/Encryption-Key-Rotation.md index a8e01f8cc..a98fa264f 100644 --- a/wiki/Encryption-Key-Rotation.md +++ b/wiki/Encryption-Key-Rotation.md @@ -16,6 +16,8 @@ TREK encrypts sensitive settings at rest using AES-256-GCM. The following values - Synology Photos password, session ID, and device ID (per user) - Per-user webhook URL, ntfy notification token, and LLM provider API key (in `settings` table) - Instance-wide API key of the AI Parsing addon (in `addons.config`) +- Credentials of the AI Assistant's connections: an API key, or the tokens of a ChatGPT sign-in, kept as one encrypted blob per connection (in `ai_connections`) +- Wanderer access token (per user, in `wanderer_connections`) - Document sync credentials of a trip's stores, one encrypted blob per store and trip (in `document_connections`), and the webhook secret of each binding (in `trip_document_links`); see [Document-Sync](Document-Sync) - OIDC client secret (global, in `app_settings`) - SMTP password (global, in `app_settings`) @@ -40,7 +42,7 @@ On startup, TREK resolves the encryption key in this order: ## What happens if the key is lost -All encrypted settings (API keys, SMTP password, OIDC secret, MFA secrets, notification tokens, etc.) become unreadable — TREK cannot decrypt them. They must be re-entered manually after the key is restored or replaced. Unencrypted data (trips, places, users, etc.) is unaffected. +All encrypted settings (API keys, SMTP password, OIDC secret, MFA secrets, notification tokens, the AI Assistant's provider key and ChatGPT sign-ins, Wanderer tokens, etc.) become unreadable — TREK cannot decrypt them. They must be re-entered manually after the key is restored or replaced. Unencrypted data (trips, places, users, etc.) is unaffected. The Web Push key pair cannot be re-entered, and TREK never replaces it on its own: unless the `VAPID_*` variables supply a pair, push stays off, with an error in the log, until TREK runs with the original key again, and then every device receives as before. To give it up instead, delete both `web_push_vapid_public_key` and `web_push_vapid_private_key` from `app_settings`. TREK then generates a new pair, and every device has to subscribe again (see [Environment-Variables](Environment-Variables#web-push)). @@ -86,6 +88,7 @@ The script: - `document_connections`: `secrets` (the one encrypted blob per store and trip, including tokens the store handed out itself, such as Synology's device token) - `trip_document_links`: `webhook_secret` - `addons.config`: the instance-wide API key of the AI Parsing addon + - `ai_connections`: `secrets` (the AI Assistant's API key or ChatGPT sign-in tokens; left out, the admin would have to enter the key again and every ChatGPT user would have to sign in anew) 5. Reports counts of migrated, already-migrated, skipped (empty), and errored values. 6. Writes the new key to `.encryption_key` next to the database, when that file exists, so the file and the secrets agree again. @@ -94,6 +97,8 @@ After a successful migration: 1. If you supply the key through `ENCRYPTION_KEY`, update it to the new value. (TREK refuses to start while the variable and the key file disagree.) 2. Restart TREK. +The rotation script does not cover the Wanderer access token. After a rotation, each user who connected Wanderer enters the token again in their settings; the rest of the connection is unaffected. + If any secrets could not be migrated, the script exits with a non-zero status and the original database backup is retained. ## Upgrading from very old versions diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 2dd1d4891..07889942c 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -7,8 +7,8 @@ Complete reference for all environment variables TREK reads. - **Docker Compose** — use the `environment:` block or a `.env` file alongside `docker-compose.yml` - **Docker run** — pass each variable with `-e VARIABLE=value` - **Helm** — use `env:` for plain values and `secretEnv:` for sensitive values in `values.yaml`. The chart only - passes through the keys it declares (37 in `templates/configmap.yaml`, the credentials in `templates/secret.yaml`), so a variable - that is not one of them (`DEFAULT_LANGUAGE`, `FILE_UPLOAD_LIMIT_MB`, `RESTORE_FROM_BACKUP` and `MCP_MAX_SESSION_PER_USER` among them) is dropped silently. Patch it onto the Deployment or add it to the chart + passes through the keys it declares in `templates/configmap.yaml` (plus the credentials in `templates/secret.yaml`), so a variable + that is not one of them (`FILE_UPLOAD_LIMIT_MB` and `RESTORE_FROM_BACKUP` among them) is dropped silently. Put it in `extraEnv` instead. - **Unraid** — set in the container template editor - **Proxmox Community Script** — set in `/opt/trek/server/.env` @@ -49,7 +49,7 @@ warning in the log; the web UI is only served with `NODE_ENV=production` in lowe |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| | `PORT` | Server port | Sources: `3001`, Docker: `3000` | | `HOST` | Bind address for the HTTP server (e.g. `127.0.0.1`, `10.0.0.72`). **Source / Proxmox installs only** — do not set this in Docker or any containerized deployment. See note below. | all interfaces | -| `NODE_ENV` | Environment (`production` / `development`) | `production` | +| `NODE_ENV` | Environment (`production` / `development`). The Docker image sets `production`; a start from source defaults to `development` | `production` | | `ENCRYPTION_KEY` | At-rest encryption key — see resolution order below | auto | | `TZ` | Timezone for logs, reminders, and cron jobs (e.g. `Europe/Berlin`) | `UTC` | | `LOG_LEVEL` | `info` = concise user actions; `debug` = verbose details | `info` | @@ -296,6 +296,12 @@ randomly generated password that is printed to the server log. Once any user exi --- +## AI Assistant + +The AI Assistant addon has no environment variables for its provider. The AI connection (provider, API key or sign-in) is set up inside TREK, and its secrets are encrypted with `ENCRYPTION_KEY`. `LLM_TIMEOUT_MS` and `LLM_MAX_OUTPUT_TOKENS` under [Booking Import](#booking-import-kde-itinerary) bound the AI calls. + +--- + ## MCP For setup instructions, see [MCP-Overview](MCP-Overview). @@ -397,6 +403,7 @@ A Google Maps API key gives place search Google as the keyed provider beside the | Variable | Description | Default | |------------------|-------------|---------| | `PLACES_API_KEY` | Google Maps API key with the **Places API (New)** enabled. When set, it takes priority over the key configured in **Admin → Settings → API Keys** and is used for every member of the instance. | unset | +| `PLACES_API_BASE` | Base URL for the Google Places calls, for routing them through an egress proxy, a cache or a gateway that speaks the same API instead of Google directly. Must be a valid URL. | unset | **Two ways to configure it**, pick one; the env var wins if both are present: @@ -461,6 +468,7 @@ 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_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--