From 18ca97ca14675587d25c549e838874a627737f17 Mon Sep 17 00:00:00 2001 From: jubnl Date: Thu, 20 Aug 2026 21:54:24 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20storage=20config=20is=20simply=20new=20?= =?UTF-8?q?in=20v4=20=E2=80=94=20drop=20the=20removed-variables=20story?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 33 ++++++--------------------------- wiki/Admin-Panel-Overview.md | 4 ++-- wiki/Admin-Storage.md | 18 +++--------------- wiki/Environment-Variables.md | 5 +---- wiki/Troubleshooting.md | 10 ---------- 5 files changed, 12 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index d31d665ff..598f59fc3 100644 --- a/README.md +++ b/README.md @@ -344,16 +344,6 @@ Your data stays in the mounted `data` and `uploads` volumes — updates never to > [!IMPORTANT] > Mount **only** the data and uploads directories — `-v ./data:/app/data -v ./uploads:/app/uploads`. **Never mount a volume at `/app`.** Doing so hides the application code shipped in the image and the container fails to start with `Cannot find module 'tsconfig-paths/register'`. If you previously mounted `/app`, switch to the two mounts above; your data in `data/` and `uploads/` is preserved. -> [!IMPORTANT] -> **Upgrading to v4 with storage variables set:** if your run command or -> compose file sets any `TREK_S3_*` variable or `TREK_UPLOADS_DIR`, the new -> version refuses to start until you remove them (better than silently -> ignoring your S3 settings and running local-only). Note the values down -> first, remove the variables, start the server, then re-enter the S3 -> credentials in **Admin → Storage** — or mount them as a -> [seed file](#storage). A relocated `TREK_UPLOADS_DIR` becomes an edit of the -> `uploads-local` backend's root in the same panel. -

Rotating the Encryption Key

If you need to rotate `ENCRYPTION_KEY` (e.g. upgrading from a version that derived encryption from `JWT_SECRET`): @@ -449,22 +439,6 @@ Caddy handles TLS and WebSockets automatically. > with a report listing every offending variable. Boolean switches accept > `true`/`false`, `1`/`0`, `on`/`off` and `yes`/`no` (any casing). -> [!WARNING] -> **Removed in v4:** storage is no longer configured through environment -> variables. `TREK_S3_ENDPOINT`, `TREK_S3_BUCKET`, `TREK_S3_ACCESS_KEY_ID`, -> `TREK_S3_SECRET_ACCESS_KEY`, `TREK_S3_REGION`, `TREK_S3_KEY_PREFIX`, -> `TREK_S3_RETRIES`, `TREK_S3_TIMEOUT_MS` and `TREK_UPLOADS_DIR` were removed, -> and a server started with any of them set **refuses to boot** with: -> -> ``` -> Invalid environment configuration: -> - TREK_S3_ENDPOINT was removed — configure storage in the admin UI or data/storage-config.json. -> ``` -> -> Unset them and configure storage in **Admin → Storage** (or the seed file) — -> see [Storage](#storage). `TREK_PLACE_PHOTO_DIR` is unaffected and keeps -> working. -
Full reference @@ -540,7 +514,10 @@ box everything lives on local disk (`uploads/` and `data/backups`). From Storing credentialed backends requires `ENCRYPTION_KEY` to be set explicitly — secrets are encrypted at rest, and the panel refuses to save a plaintext -secret without it. +secret without it. On an existing install that has been running without an +explicit key, do not just set a new one — that would orphan already-stored +secrets; use the key-rotation procedure (see *Rotating the Encryption Key* +under Updating) to move to an explicit key first. Notes and limits: reassigning a populated category does not move its existing objects (new writes go to the new backend, old objects stay); media categories @@ -575,6 +552,8 @@ stored storage configuration, and loudly ignored afterwards: } ``` +(The panel presents this exact setup as **Mirror targets** on `backups-local`.) + ```yaml # docker-compose: add under the trek service's volumes - ./storage-config.json:/app/data/storage-config.json:ro diff --git a/wiki/Admin-Panel-Overview.md b/wiki/Admin-Panel-Overview.md index 880bd674b..088f99f22 100644 --- a/wiki/Admin-Panel-Overview.md +++ b/wiki/Admin-Panel-Overview.md @@ -22,10 +22,10 @@ The Admin Panel is divided into tabs. Most tabs are always visible; a few appear | **Storage** | Storage backends, category assignment, replication, health | Hidden on managed instances | | **Settings** | Authentication methods, MFA, allowed file types, API keys, OIDC/SSO configuration, and JWT secret rotation | No | | **Notifications** | SMTP, webhook, ntfy, and push notification channel configuration; trip reminder toggle; admin notification preferences | No | -| **Backup** | Manual and scheduled database backups | No | +| **Backup** | Manual and scheduled database backups | Hidden on managed instances | | **Audit** | Chronological activity log | No | | **MCP Access** | OAuth sessions and static API tokens | Only when the MCP addon is enabled | -| **GitHub** | Release timeline and support links | No | +| **GitHub** | Release timeline and support links | Hidden on managed instances | | **Dev: Notifications** | Test notification dispatch | Only in development mode (`NODE_ENV=development`) | ![Admin panel on the User Defaults tab, setting instance-wide defaults for colour mode, temperature unit, distance unit, time format, currency and blurred booking codes](assets/AdminUserDefaults.png) diff --git a/wiki/Admin-Storage.md b/wiki/Admin-Storage.md index 29b6d628f..03bf30111 100644 --- a/wiki/Admin-Storage.md +++ b/wiki/Admin-Storage.md @@ -73,8 +73,9 @@ assigned to exactly one backend: Reassigning a category changes where **new** objects go — existing objects do not move and keep being served from wherever they already are. The panel -shows this warning inline when you change an assignment. Replicating the two -re-fetchable caches is possible but flagged as not recommended. +shows this warning inline when you change an assignment. Replicating the +Google photo cache or Place images is flagged as not recommended — both hold +content that is re-fetchable or provider-derived. The legacy `/uploads/photos` directory written by older TREK versions is not a category: its files are still served and included in backups, but nothing @@ -108,19 +109,6 @@ your only backup lives on S3 and the credentials are inside it: start a fresh instance, enter the S3 credentials here (or mount a seed file), then restore from the Backup panel. -## Removed environment variables - -Storage used to be configured through `TREK_S3_*` and `TREK_UPLOADS_DIR`. -These were **removed in v4** and a server started with any of them set -refuses to boot, naming each offending variable: - -``` - - TREK_S3_ENDPOINT was removed — configure storage in the admin UI or data/storage-config.json. -``` - -Remove the variables and configure the equivalent here. `TREK_PLACE_PHOTO_DIR` -is unaffected. - ## Related pages - [[Backups|Backups]] — what a backup contains, restore procedure diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 7bdf15e45..a32a23dcf 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -277,10 +277,7 @@ To get a key: create a free account at [unsplash.com/developers](https://unsplas Storage backends and category assignment are configured in [[Admin: Storage|Admin-Storage]] (or a seed-once `storage-config.json`), not -through environment variables. The former `TREK_S3_*` and `TREK_UPLOADS_DIR` -variables were removed in v4 — a server started with any of them set refuses -to boot and names the offending variable. `TREK_PLACE_PHOTO_DIR` below is -unaffected. +through environment variables. `TREK_PLACE_PHOTO_DIR` below is unaffected. | Variable | Description | Default | |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md index 09f65781f..28d6ef815 100644 --- a/wiki/Troubleshooting.md +++ b/wiki/Troubleshooting.md @@ -145,16 +145,6 @@ sudo chown -R 1000:1000 ./data ./uploads --- -## Server refuses to start after updating: "TREK_S3_ENDPOINT was removed" - -Storage is no longer configured through environment variables (v4). Remove -every `TREK_S3_*` variable and `TREK_UPLOADS_DIR` from your run command or -compose file, start the server, and configure the equivalent in -[[Admin: Storage|Admin-Storage]] or via a seed-once `storage-config.json`. -The boot report lists each offending variable by name. - ---- - ## Container won't start: "exec /usr/bin/dumb-init: operation not permitted" **Symptoms:** The container restarts in a loop and the logs show nothing but: