mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-19 13:36:48 +00:00
jubnl
305b113d5f
* feat(storage): storage key validation, driver contract suite, LocalDriver * feat(storage): MirrorDriver composite backend * feat(server): add TREK_UPLOADS_DIR env var for the uploads root * feat(storage): settings-backed registry, StorageService facade, module wiring * test(storage): pin src/nest/storage coverage thresholds * feat(storage): multer upload options factory * refactor(files): spool trip-file uploads through storage * refactor(collab): spool note attachments through storage; normalize files/ prefix * refactor(journey): spool journey media uploads through storage * refactor(trips): spool trip cover upload through storage * refactor(places): spool place-image and collection uploads through storage * refactor(auth): spool avatar upload through storage * fix(server): consolidate allowed_file_types onto AllowedFileTypesService * fix(storage): default defParamCharset to utf8 in the upload factory * test(db): re-point the trailing-migration guard at the trip_files prefix strip * fix(storage): age-gate the boot spool sweep * test(files): key FILE-P02 residue checks on upload size * test(storage): raise src/nest/storage coverage pin * refactor(platform): serve /uploads routes through storage * refactor(files): serve trip-file downloads through storage * refactor(memories): serve photo bytes through storage * refactor(maps): stream place-photo bytes through storage * refactor(share): stream shared place-photo bytes through storage * refactor(journey): serve public journey assets through storage * fix(share): answer place-photo cache miss with 204 like the maps proxy * test(server): close serving-swap gaps surfaced by the full tier * test(storage): raise src/nest/storage branches pin * refactor(place-photos): route place-photo cache through storage * refactor(places): reclaim place images and collection covers through storage * refactor(trips): trip covers through storage * refactor(auth): avatar reclaim through storage * refactor(collab): note-file deletion through storage * refactor(files): trash deletion through storage * refactor(memories): trek photo cache internals through storage * refactor(memories): thumbnail service category-addressed * refactor(memories): immich upload reads through storage; drop uploads-root * refactor(journey): photo deletion through storage * fix(memories): reclaim orphaned trek photo cache objects in the ttl sweep * feat(journey): journey-thumbs orphan sweep and delete-site derived-artifact reclaim * test(server): close slice-4 gaps surfaced by the full tier * test(coverage): raise slice-4 domain pins * refactor(backup): list, existence and delete through storage * refactor(backup): download through storage sendToResponse * refactor(backup): create backup through per-category storage enumeration * refactor(backup): restore and upload-restore through storage * refactor(backup): auto-backup retention through storage * refactor(server): boot dir-creation to driver init * test(server): close slice-5 gaps surfaced by the coverage tier * test(coverage): raise slice-5 backup pin * test(server): resolve async backupFileExists mocks for the tests typecheck * test(server): pin ranged-read stat and zero-byte roundtrip in the storage driver contract * feat(server): TREK_S3_* env wiring — schema, s3 namespace, all-or-nothing boot rule * feat(server): S3 driver core — aws-lite client seam, stat/delete, driver-owned deadlines * refactor(server): type the aws-lite S3 client via s3-types reference * feat(server): S3 driver getStream and list — ranged full-object stat, iterator pagination * feat(server): S3 driver put — bounded-peek routing, Upload inactivity deadline * fix(server): S3 driver Upload monitoring — Transform interposition, stream cleanup * feat(server): env-declared s3-main storage backend; settings-declared s3 rejected * test(server): env-gated S3 driver contract suite against MinIO * fix(server): S3 driver zero-byte put — work around aws4 duplicate Content-Length signing defect * fix(server): scope the zero-byte put workaround to buffered bodies; bind test MinIO to localhost * ci(server): MinIO-backed S3 driver contract job * ci(server): align s3-contract shim comment and MinIO bind with references * docs: S3 storage backend configuration and off-box backup mirroring * docs: restore README formatting, keep S3 additions only * ci(server): make live-MinIO contract runs manual-only (AIStor licensing) MinIO's community line is discontinued entirely; the maintained successor, AIStor, requires a license key that can't safely live in a shared CI runner. The s3-contract CI job is removed; live-provider contract runs against MinIO/AIStor are now a manual, license-gated procedure documented in docker-compose.minio-test.yml's header. * chore(server): final-review polish — stale CI refs, dockerignore key, boundary pins, zero-byte tempfile contract case * expose admin ui * feat(shared): storage backend type registry, wire schemas, category relocation * feat(server): accept settings-declared s3 backends — shared-schema options, decrypt-at-build, registry preview() * feat(server): remove TREK_S3_*/TREK_UPLOADS_DIR — tombstone boot rule, built-in override as the relocation path * feat(server): deriveSecurity.encryptionKeySet and storage secret plumbing (gate, encrypt, unmask, mask, redact) * chore(server): drop storage-secrets import that only Task 8's probe helper will use * feat(server): seed-once storage-config.json boot import — fail closed on any invalid seed * feat(server): registry snapshot() — effective storage config with provenance * feat(server): api/admin/storage GET/PUT — masked secrets, preview-gated saves, wired reload, audits * feat(server): api/admin/storage/test — per-target ephemeral probes, mirror targets probed individually * test(server): e2e coverage for api/admin/storage — guards, managed refusal, envelope, probes * test(server): give e2e harness DBs the app_settings table the storage registry reads at boot * test(coverage): raise pins after the storage admin-config slice * fix(server): final-review polish — encryption-gate wording, all-field sentinel guard, README/e2e notes * test(server): storage slice-1 review follow-ups — mirror s3-replica probe decrypt, all-encrypted seed without key, test-route 401 * feat(i18n): storage admin domain + tab label in every locale * feat(client): adminApi storage endpoints — getStorage, updateStorage, testStorageBackend * feat(client): storage admin draft-document helpers + relative-time util * feat(client): schema-driven storage BackendForm — fields by kind, mask echo, encryption banner * feat(client): admin storage panel — backends list, category map, health strip, one-PUT save * feat(client): storage tab on the admin page * feat(client): storage admin panel and section on the phone shell * fix(client): block renaming a storage backend onto an existing name * feat(server): allow mirrors on any storage category — lift the backups-only rule * feat(i18n): replicas-on-primary mirror strings in every locale * feat(client): mirror fold/synthesize model helpers for replicas-on-primary * feat(client): BackendForm mirror-targets composer; raw mirror type hidden * feat(client): desktop storage panel folds mirrors into their primaries * feat(client): phone storage panel folds mirrors into their primaries * fix(client): strip removed backends from remaining mirror replicas — no phantom refs * feat(storage): retire photos as a configurable category — served-only via the ServedCategory seam * feat(i18n): descriptive storage category names and descriptions in every locale * feat(client): descriptive category names, descriptions and id badges in the storage panel * docs(storage): fix stale nine-category comments after the eight-category shrink * docs: storage configuration via the admin UI and seed file — README + compose * docs(wiki): Admin Storage page and storage cross-links * docs(server): storage domain blueprint entry; TREK_PLACE_PHOTO_DIR tombstone clarifier * refactor(server): drop the storage env-var tombstones — the variables never shipped * docs: storage config is simply new in v4 — drop the removed-variables story * feat(shared): backfill-status and usage wire schemas on the storage admin state * feat(server): MirrorDriver.backfill — prefix-scoped, size-compared, cancellable replica catch-up * feat(server): one-at-a-time storage backfill jobs + the storage events bridge * feat(server): storage usage scan — nightly cron, on-demand service, persisted with computedAt * feat(server): replica_failure admin notifications — events bridge, hourly debounce, channel registration * feat(i18n): replica-failure notification text in every locale * feat(server): storage backfill and stats-refresh admin endpoints * feat(client): adminApi backfill and stats-refresh endpoints * feat(i18n): storage sync and usage strings in every locale * feat(client): desktop storage panel — sync now, usage display, backfill polling * feat(client): phone storage panel — sync now, usage display, backfill polling * fix(client): per-category usage line on the phone storage panel * docs: sync now, usage stats and replica-failure notifications * test(server): admin scope now includes replica_failure, not just version_available Commit6db135daadded replica_failure to ADMIN_SCOPED_EVENTS but left NPREF-005b asserting the admin scope contained only version_available. Update the expectation to match. * test(server): cover storage backfill/stats/jobs branches to hold the coverage pin * fix(client): guard storage admin polling against stale responses racing a save A poll GET issued before a save's PUT resolves could land after the save applied its fresher response, overwriting it with the pre-save world and re-deriving the draft from that stale snapshot. useStorageAdmin now tracks a state-application sequence number and drops any refreshState() response whose sequence has moved on, or that resolves while a save is in flight. Also guard the fire-and-forget refreshState() calls in startBackfill/ cancelBackfill against unhandled rejections, matching the poll's style. * fix(server): report 404 before 409 when a backfill start names an unknown mirror startBackfill checked the global busy flag before validating that :name is a mirror routed by some category, so POST .../backends/garbage/backfill answered 409 instead of 404 whenever a sync was already running. Resolve and validate the target first (BackfillTargetError -> 404), then check busy (BackfillBusyError -> 409). * feat(client): two-column category grid on the storage panel * feat(server): plugin files.getContent reads through the storage layer * feat(server): plugin files.create writes through the storage layer * refactor(server): drop FilesService.resolveFilePath, last direct-fs seam in the plugin surface * fix(server): map StorageInvalidKeyError to the plugin file accessibility envelope * feat(storage): allow credentialed backends without an explicit ENCRYPTION_KEY Secrets are still always encrypted at rest; without an explicit key the implicit data-directory key is used. Removes the plaintext-secret refusal from the admin PUT and the seed import, the encryptionReady GET field, the save-blocking banner in both admin shells, and the now-consumerless security.encryptionKeySet env derivation. Docs now recommend (not require) an explicit key, since the implicit key rides inside backup archives. * test(client): pin the stale-poll release to the pre-save GET in FE-ADMIN-STOR-024 The stub deferred EVERY poll GET and rebound the release handle to the newest one, so a tick landing after the save was released with the pre-save payload — a response no real backend can produce, which the seq guard rightly applied. Only the first (genuinely stale) GET is held now; later GETs answer with the world the mock server currently holds. Also drops the encryptionReady fixture field removed from the schema in the previous commit. * fix(storage): backfill puts carry content-type, stat failures report op stat, progress clamps * feat(storage): category migration job — copy, flip, delta sweep, reclaimable tally * feat(storage): migration start/cancel endpoints and client API * test(client): storage admin fixtures carry the new migrations field * fix(storage): migration POST answers 200 and validates its body via the shared schema * fix(storage): cancel running storage jobs when a config save removes their backend * fix(notifications): in-app replica-failure row carries the suppressed count * feat(client): migration prompt, queue, and progress on the storage panel * fix(client): migration queue holds a synchronous single-flight lock * feat(client): migration prompt and progress on the mobile storage panel * fix(server): register category-migration routes in the managed-route allow list StorageAdminController.migrationStart/migrationCancel were added under the controller-level @ManagedForbidden() decorator but never added to MANAGED_ROUTE_ALLOW_LIST, so validateManagedRoutes() threw "Managed surface changed" on every buildApp() call, failing 46 test files (any test booting the real app). * test(server): cover category-migration copy/sweep branches to hold the storage coverage pin Adds MIG-005 (a target object already matching size/key is skipped in the copy phase itself, not just the delta sweep) and MIG-006 (a copy failure during the delta sweep is counted without undoing the flip that already happened). src/nest/storage/**'s branch coverage was 83.91%, just under the 84% pin. * docs(storage): category migration — move existing objects on reassign * fix(storage): close the pre-flip cancel window and cancel re-routed migrations A cancel landing between the last copy iteration and the category flip was silently ignored, and a config save that re-routed the migrating category to a third, still-defined backend never stopped the in-flight migration. Also guards assignCategory against writing an unknown backend name, and fixes a missing `suppressed` notification param being treated as truthy suppression. * fix(client): migrations keep mirrors, queue waits on backfills, sweep failures surface Reassigning a category onto a mirrored primary now posts the migration to the mirror's wire name instead of the bare primary, so replication survives the move. The queued-migration effect also waits out a running backfill (the server's one-job rule spans both), and a done migration with sweep failures now surfaces a doneFailures line in both shells, translated into every locale. * ci(server): run the S3 contract suite against MinIO Resurrects the s3-contract job removed in6fbff835, adapted for AIStor: writes the MINIO_LICENSE_KEY secret to a license file, boots the licensed container, and runs the contract suite hermetically (no --coverage) so the storage coverage pin keeps holding from unit tests alone. Gated to same-repo PRs since fork PRs have no access to the license secret. * fix(server): backup archives uploads from a remote primary createBackup() enumerated uploads through withLocalFile, which downloads a remote object to a temp file, hands it to the callback, then deletes it before archiver ever reads it — archiver reads entries lazily during finalize(), so a remote (S3) primary silently backed up zero upload bytes. Add StorageService.getLocalPathOrNull(category, name): a narrow locality probe that returns a real path only when one exists on disk right now (the fs-existence check is the fail-safe half of the contract — a driver-reported path that vanished between list() and here falls back too, not just a path-less remote driver). The enumeration loop uses it directly when available (zero-copy, unchanged for a local primary) and otherwise streams the object into a per-backup staging dir under the backups spool, cleaned up in the existing finally alongside zipSpool/dbSnap. Also wire archive.on('warning', reject): archiver treats a missing/unreadable entry as a warning, not an error, and skips it by default — which would silently drop the entry from an otherwise "successful" backup. * fix(server): client aborts stop 500ing and leaking streams storage.service.ts sendToResponse: the local res.sendFile branch now treats ECONNABORTED/ECONNRESET/ERR_STREAM_PREMATURE_CLOSE/syscall=write as success, mirroring res.sendFile's own default callback (the contract storageStaticHandler already implements caller-side). The remote branch replaces the hand-rolled pipe+Promise with pipeline(stream, res), which destroys the source stream on any failure — fixing the leaked S3 keep-alive socket on a client abort — while swallowing the same client-abort error set; a real source error still rejects so callers keep their miss contracts. This centralizes the fix for every caller that streams through sendToResponse: files-download, journey-public, photo-resolver, trek-photo-cache, backup downloads, and /uploads/photos. trek-exception.filter.ts now no-ops (destroying the socket) when headers are already sent, so no filter path ever writes onto a response in flight. maps.controller.ts and share.controller.ts's place-photo bytes proxies switch their direct getStream+pipe to pipeline() with the same abort-tolerant catch, keeping the existing 204-empty fallback for pre-header failures. * fix(storage): mirror read fallback consults replicas on primary miss MirrorDriver.getStream/stat now fall back to replicas on a primary miss (StorageNotFoundError / null stat), not just an infra error — binding decision: a read succeeds if ANY member holds the object. Only a deterministic StorageInvalidKeyError skips fallback. stat() gets a dedicated fallback loop instead of reusing fromReplicas: a replica returning null means "keep looking," which the generic catch-and-continue helper would have short-circuited on. StorageService.sendToResponse/withLocalFile stop treating composite driver.stat() as proof the object is at localPath; both now fs-check the path itself and fall through to the stream branch when it's missing, which is what actually reaches a MirrorDriver's replicas. * feat(storage): remote serving parity — content-type, validators, range Local backends get content type, ETag/Last-Modified, conditional GET, Range and HEAD for free from res.sendFile; the proxying branch every remote backend (and a local primary whose file vanished) falls through to had none of it — every request re-streamed the whole object with no cache validator and no way to seek. sendStreamed() reproduces the contract from ONE pre-flight driver.stat(): a miss throws before any header is set (the caller's 404/204/next() contract), and that same stat then answers 304s, 416s, HEADs and suffix ranges without ever opening a body. The decisions live in a new pure module, http-serving.ts: - validatorsFor: the driver's ETag, else express/send's weak W/"<size hex>-<mtime hex>". mtimeMs 0 (S3 can report it) means no Last-Modified and no derived tag — serving uncached beats a 1970 header that reads as fresh forever. - isNotModified: If-None-Match (weak compare, *, list) wins over If-Modified-Since, per RFC 9110 §13.2.2. - decideRange: single range only, inclusive clamp, suffix computed from the pre-stat size, unsatisfiable → 416, If-Range strong-exact or full entity. A multi-range or malformed spec is answered with the full object rather than multipart/byteranges. If-Match/If-Unmodified-Since stay out of scope. Range math uses the pre-stat size as the single source of truth, the ranged getStream stat is never re-consulted, and the pipeline abort semantics are unchanged. S3Driver now surfaces the bucket's ETag on stat()/getStream() (on a ranged GET it is still the full object's tag). aws-lite strips the tag's surrounding quotes — verified live against AIStor RELEASE.2026-08-07 — and an unquoted entity-tag is not a valid HTTP ETag, so the driver restores exactly the quotes the SDK removed and nothing else. * fix(server): key rotation covers storage.backends The S3 storage backend's secretAccessKey is encrypted at rest inside the app_settings row keyed storage.backends, but scripts/migrate-encryption.ts didn't know about it — after a key rotation that secret stayed encrypted under the old key and silently failed to decrypt on the next read. The script now re-encrypts secretAccessKey for every s3 backend inside the storage.backends JSON array, using a pinned copy of the secret-field list (it deliberately can't import @trek/shared). The parity test pins that copy against storageSecretFields('s3') so a new secret field can't be missed silently. * fix(server): restore reloads the storage registry restoreFromZip closed and reopened the DB but never reloaded the storage registry, so uploads rehydration ran against the STALE pre-restore driver/category map instead of the config the restored archive's own travel.db carries (audit #4, major). StorageService gains reloadConfig(), a narrow passthrough to the (unexported) registry's reload() — same shape as health(). backup.impl's restoreFromZip now calls it right after reinitialize() and right before the uploads wipe/rehydrateUploads/plugin staging, so rehydrated bytes land where the restored config says. When reopen fails (reinitFailed), reload and rehydration are skipped entirely — already reported as "restart required", and there is no live DB handle for the registry to read anyway. * fix(server): category migration rewrites keys across prefix changes Category migration copied objects to the destination backend using the SOURCE key verbatim. A mode-A ('' prefix) source migrating onto a prefixed backend (or vice versa) landed objects at keys the registry could never resolve post-flip (audit #8). Extracts StorageRegistryService.keyPrefixFor(category, backendName) from build()'s inline conditional so startMigration can compute the destination prefix before the flip. runMigration now maps every destination key (destPrefix + key.slice(sourcePrefix.length)) in the copy skip-check, the put, and the delta sweep; the reclaimable tally stays source-keyed. Equal-prefix migrations are unaffected (identity mapping). * fix(plugins): await the now-async place/collection services in RPCs PlacesService.update/remove and CollectionsService.deletePlace became async when they started deleting storage objects, but their plugin RPC handlers still called them synchronously: the null/false refusal check compared against an always-truthy Promise, and places.update broadcast a Promise instead of the resolved place. Both handlers now await the service call; mapCollectionError is async-aware (accepts a sync-or- async thunk) so the sync callers (create/update/savePlace/copyToTrip) keep working through the same path. Verified the RPC host already awaits handler results, so no change was needed there. * fix(storage): backfill Sync now gains a deletion sweep The Sync now backfill copied primary objects to replicas but never removed replica objects the primary no longer has, leaving mirror read-fallback able to serve stale data indefinitely after a failed replica delete. backfill() now sweeps each replica post-copy: any replica key absent from the primary key-set is re-checked against primary.stat (a race gate against the primary regaining the key) before being deleted. Adds a deleted counter end-to-end (driver, jobs service, shared schema, both admin shells, all 23 locales) and a new ReplicaFailure 'list' op for a replica whose listing itself fails during the sweep. * feat(storage): optimistic concurrency for admin config saves A stale admin PUT of storage settings could silently undo a category migration's just-flipped assignment. Adds a version counter (app_settings row storage.config_version) bumped inside the same transaction by both writers — applyConfig and the migration flip (assignCategory). applyConfig compares the submitted version first and throws StorageConflictError, mapped to 409 ahead of the blanket 400. The client carries the draft's loaded version through every local edit and maps a 409 to a distinct "settings changed underneath you" message, refreshing state while preserving the dirty draft for review. * fix(storage): surface a failed config load + redact secretAccessKey Registry load() now records the exact parse/validate failure as lastLoadError() instead of silently falling back to last-good config or built-in defaults; StorageAdminService exposes it as configError on the admin state (storageAdminStateSchema extended additively), and AdminStoragePanel renders it as a warning banner naming the error. Save stays enabled — it's the recovery path — but an admin can no longer save over a broken stored config without knowing. Also adds 'secretaccesskey' to globalMiddleware's SENSITIVE_KEYS request-log redaction list, so storage admin PUT bodies never leak the S3 secret into debug logs. * fix(client): admin storage panel state races Migration prompt now recomputes computeMigrationCandidates(draft, state) on render and again at confirm time, so a stale open-time snapshot never drives stripCategories or the migration queue; adds a Cancel button to the dialog. A failed startMigration POST explicitly clears the remaining queue with a toast naming the dropped categories and refreshes state, instead of leaving it invisibly stranded; a "Queued: X, Y" line renders while the queue is non-empty. Testing a mirrored row now expands the draft primary + replicas client-side and probes each individually, instead of sending the mirror stub to the server (which resolved targets from its own live snapshot, silently testing saved options over unsaved draft edits). A completed/cancelled/errored backfill now renders its terminal status alongside the Sync now button instead of hiding it, so it can be re-run without a page reload. * fix(storage): refuse shared replica backends so the sync sweep cannot cross categories A mirror's "Sync now" sweep makes each replica MATCH the primary: it lists the replica under every prefix the mirror's categories occupy and deletes the keys the primary doesn't hold. The backups category's prefix is '' — the replica's entire root — so making a category-serving backend (say uploads-local) a replica of a backups mirror meant the first sync deleted every user upload. Nothing forbade the config: validateConfig only checked that mirror targets existed and weren't nested, and the admin picker offered every backend. The sweep is correct, so the fix is at the config level: - validateConfig refuses a backend that is both a mirror replica and a category target (directly, or as the primary of a mirror a category routes to), and refuses a backend replicating two mirrors whose swept prefixes overlap — '' overlaps everything. Disjoint prefixes stay legal. - assignCategory (the migration flip, the other writer of the settings rows) refuses routing a category onto a backend that is currently a replica. - The admin mirror-target picker (both shells) only offers backends that serve no category; already-selected targets stay listed so they can be unchecked. A category assigned to a replica still surfaces the server's 400 verbatim. Existing shared-replica fixtures were rewritten onto dedicated replicas. * fix(client): a 409 conflict save is recoverable without a page reload After a 409 the admin storage panel was a dead end. refreshState leaves a dirty draft's version alone on purpose (audit #7: the background poll must never float a mid-edit draft past a migration flip it never carried), setDraft re-attaches that same version to every later edit, and save() resubmits it — so every retry 409s again and only a full page reload got the operator out, while the banner told them to "review and save again". The version block stays. Instead the conflict banner now offers the one action that can clear it: discard the local edits and reload the saved settings — a fresh GET applied through applyState, re-deriving the draft (and its version) and clearing dirty/saveError. Bumping the version in refreshState, or only in the 409 branch, was rejected: either resurrects audit #7, since a full-document save would then revert a flip the draft never carried. storage.saveConflict now points at that action instead of implying a plain re-save works (all 23 locales). The escape lives in the shared hook, so the phone panel renders it too. * fix(client): deflake the queued-migration-waits-out-backfill panel test FE-ADMIN-STOR-037 seeds a running backfill, so the panel polls GET from first render — but the stub served the post-save world (files: off-box) before the PUT had landed, which no real server would do. A poll resolving while the confirm dialog was open made the confirm-time candidate recompute see from === to, so nothing was queued and the migration never POSTed. The GET stub now stays faithful (pre-save world until the PUT lands, usage included so candidates keep their object counts), and the test deterministically forces the once-flaky interleaving: it waits for polls to land while the dialog is open and asserts the candidate survives them. * fix(storage): surface the underlying cause in probe target errors The admin storage Test probe reported only the driver wrapper's outer message ("put failed for '…' on 'probe-s3'"), dropping the cause that says WHY — connection refused vs missing bucket. Flatten the error's cause chain into the probe result, appending an S3-style code when it isn't already in the message. * fix(storage): surface the underlying cause in replica-failure reports Same defect as the probe fix, one layer over: MirrorDriver's reportReplicaFailure captured only the wrapper's message, so replica-failure notifications said "put failed" without the why. Move the probe's cause-chain flattener into storage.types.ts as describeError and use it in both call sites. * fix(storage): strip ContentType from multipart Upload calls (MalformedXML) Every multipart S3 put carrying a contentType — every backup zip and photo over the 10MB threshold — failed with 400 MalformedXML. Upstream @aws-lite/s3's Upload leaks the ContentType param into its final CompleteMultipartUpload headers ({ ...xml, ...paramHeaders }), clobbering application/xml, which flips @aws-lite/client's payload serializer to JSON — so the server receives a JSON parts list where XML belongs. Confirmed live against MinIO AIStor; any S3 refuses the same. uploadMonitored now drops ContentType before s3.Upload. Multipart objects are stored without a content-type, which TREK never reads back (serving derives Content-Type from the key/caller, never object metadata); single-request PutObject paths keep sending it. Also closes the coverage gap that let this ship: the live contract suite never crossed MULTIPART_THRESHOLD, so s3.Upload had never run against a real server — it now round-trips a >10MB put carrying a contentType. --------- Co-authored-by: Maurice <mauriceboe@icloud.com>
370 lines
44 KiB
Markdown
370 lines
44 KiB
Markdown
# Environment Variables
|
|
|
|
Complete reference for all environment variables TREK reads.
|
|
|
|
## How to Set Variables
|
|
|
|
- **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`
|
|
- **Unraid** — set in the container template editor
|
|
- **Proxmox Community Script** — set in `/opt/trek/server/.env`
|
|
|
|
---
|
|
|
|
## Core
|
|
|
|
| Variable | Description | Default |
|
|
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|
|
|
| `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` |
|
|
| `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` |
|
|
| `DEFAULT_LANGUAGE` | Default language on the login page — see supported codes below | `en` |
|
|
| `SESSION_DURATION` | How long a login session stays valid before re-login is required. Used when **"Remember me" is unchecked** on the login form (the default): applies to the `trek_session` JWT `exp` claim, and the cookie is issued as a **browser-session cookie** (no `maxAge`, cleared when the browser closes). Accepts `ms`-style strings: `1h`, `12h`, `7d`, `30d`, `90d`. Invalid values warn at startup and fall back to the default. Does not affect the short-lived MFA challenge token or MCP OAuth tokens (those keep their own TTL). | `24h` |
|
|
| `SESSION_DURATION_REMEMBER` | Session length used when the user **ticks "Remember me"** on login: a longer-lived JWT `exp` claim plus a **persistent** `trek_session` cookie whose `maxAge` matches, so the session survives browser restarts. Same `ms`-style format and startup-fallback behaviour as `SESSION_DURATION`. | `30d` |
|
|
| `ALLOWED_ORIGINS` | Comma-separated origins for CORS and email notification links | same-origin |
|
|
| `ALLOW_INTERNAL_NETWORK` | Allow outbound requests to private/RFC-1918 IPs. Set `true` if Immich or other integrated services are on your local network. Loopback (`127.x`) and link-local (`169.254.x`) addresses remain blocked regardless. | `false` |
|
|
| `APP_URL` | Public base URL (e.g. `https://trek.example.com`). Required when OIDC is enabled — must match the redirect URI registered with your IdP. Also used as the base URL for email notification links and subscribable calendar feed URLs (the `webcal://`/`https://` links the Subscribe dialog hands to Google/Apple/Outlook). | — |
|
|
| `TREK_WIKI_DIR` | Where the in-app Help pages (`/help`) read their content from. TREK ships this wiki and serves it from disk, so the docs always match the version you are running. You should not need to set this — it is an escape hatch for unusual layouts. If the directory cannot be found, Help falls back to fetching the public GitHub wiki (which tracks the latest release and needs outbound network access). | the bundled `wiki/` directory |
|
|
|
|
### `HOST` — Source and Proxmox installs only
|
|
|
|
By default TREK binds to all network interfaces (`0.0.0.0`), which is the correct behaviour inside a container because
|
|
Docker handles port exposure at the host level. Setting `HOST` overrides the bind address at the Node.js level.
|
|
|
|
**When to use it:** only when running TREK directly on a host (git sources or
|
|
the [Proxmox community script](Install-Proxmox)) and you need to restrict which interface the server listens on — for
|
|
example, to expose TREK only on a LAN interface while keeping it off the public-facing one.
|
|
|
|
**Never set `HOST` in Docker, Docker Compose, Helm, or Unraid deployments.** Use Docker's
|
|
`-p <host-ip>:<host-port>:<container-port>` syntax or your orchestrator's port binding instead.
|
|
|
|
```
|
|
# .env — source / Proxmox installs only
|
|
HOST=10.0.0.72 # bind only on this LAN interface
|
|
PORT=3001
|
|
```
|
|
|
|
When `HOST` is set, the startup banner includes a `Host:` line confirming the bound address.
|
|
|
|
### `ENCRYPTION_KEY` — Resolution Order
|
|
|
|
`server/src/config.ts` resolves the encryption key in this order:
|
|
|
|
1. **`ENCRYPTION_KEY` env var** — explicit value, always takes priority. Persisted to `data/.encryption_key`
|
|
automatically.
|
|
2. **`data/.encryption_key` file** — present on any install that has started at least once.
|
|
3. **`data/.jwt_secret` file** — one-time fallback for existing installs upgrading without a pre-set key. The value is
|
|
immediately persisted to `data/.encryption_key` so JWT rotation cannot break decryption later.
|
|
4. **Auto-generated** — fresh install with none of the above; persisted to `data/.encryption_key`.
|
|
|
|
Setting `ENCRYPTION_KEY` explicitly is recommended so you can back it up independently of the data volume.
|
|
|
|
### `DEFAULT_LANGUAGE` — Supported Codes
|
|
|
|
You can set `DEFAULT_LANGUAGE` to any of the 22 languages TREK ships. The currently supported codes are:
|
|
|
|
| Code | Language |
|
|
|---------|--------------------|
|
|
| `en` | English |
|
|
| `de` | Deutsch |
|
|
| `es` | Español |
|
|
| `fr` | Français |
|
|
| `hu` | Magyar |
|
|
| `nl` | Nederlands |
|
|
| `br` | Português (Brasil) |
|
|
| `cs` | Česky |
|
|
| `pl` | Polski |
|
|
| `ru` | Русский |
|
|
| `zh` | 简体中文 |
|
|
| `zh-TW` | 繁體中文 |
|
|
| `it` | Italiano |
|
|
| `tr` | Türkçe |
|
|
| `ar` | العربية |
|
|
| `id` | Bahasa Indonesia |
|
|
| `ja` | 日本語 |
|
|
| `ko` | 한국어 |
|
|
| `uk` | Українська |
|
|
| `gr` | Ελληνικά |
|
|
| `sv` | Svenska |
|
|
| `vi` | Tiếng Việt |
|
|
|
|
If you set a code that isn't supported, TREK falls back to English (`en`). This list grows as new
|
|
translations are added to TREK.
|
|
|
|
---
|
|
|
|
## Outbound HTTP(S) Proxy
|
|
|
|
TREK can route supported outbound HTTP(S) requests through a proxy by setting the standard variables below. Outbound
|
|
proxying is disabled by default.
|
|
|
|
| Variable | Description | Default |
|
|
|---------------|---------------------------------------------------------------|---------|
|
|
| `HTTP_PROXY` | Proxy URL for outbound HTTP requests | — |
|
|
| `HTTPS_PROXY` | Proxy URL for outbound HTTPS requests | — |
|
|
| `NO_PROXY` | Comma-separated hosts or domains that should bypass the proxy | — |
|
|
|
|
> **Note:** Proxy environment variables apply to requests made through Node.js's default HTTP dispatcher. Requests
|
|
> handled by TREK's SSRF protection use a dedicated dispatcher and do not use the environment proxy.
|
|
|
|
> **Container only.** Node ignores these variables unless it is started with `NODE_USE_ENV_PROXY=1`, and the official
|
|
> image sets that for you. On a source or Proxmox install, and on Helm where the chart's ConfigMap only passes through
|
|
> the keys it knows, set `NODE_USE_ENV_PROXY=1` alongside them or nothing will change.
|
|
|
|
> **Set `NO_PROXY`.** Without it every request goes to the proxy, including the ones TREK makes to itself, such as the
|
|
> container health check. `localhost,127.0.0.1` is a sensible minimum; add your own hosts as needed.
|
|
|
|
---
|
|
|
|
## HTTPS / Reverse Proxy
|
|
|
|
These three variables work together behind a TLS-terminating reverse proxy. See [Reverse-Proxy](Reverse-Proxy) for the
|
|
full explanation.
|
|
|
|
| Variable | Description | Default |
|
|
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
|
|
| `FORCE_HTTPS` | When `true`: 301-redirects HTTP→HTTPS, sends HSTS (`max-age=31536000`), adds CSP `upgrade-insecure-requests`, forces cookie `secure` flag. Only useful behind a TLS proxy. Requires `TRUST_PROXY`. | `false` |
|
|
| `HSTS_INCLUDE_SUBDOMAINS` | When `true`: adds the `includeSubDomains` directive to the HSTS header, extending HTTPS enforcement to all subdomains. Only effective when HSTS is active (`FORCE_HTTPS=true` or `NODE_ENV=production`). Leave `false` if you run other services on sibling subdomains over plain HTTP. | `false` |
|
|
| `TRUST_PROXY` | Number of trusted proxy hops. Tells Express to read the real client IP from `X-Forwarded-For` and protocol from `X-Forwarded-Proto`. Defaults to `1` automatically in production. Required for `FORCE_HTTPS` to detect the forwarded protocol. | `1` (production) |
|
|
| `COOKIE_SECURE` | Controls the `secure` flag on the `trek_session` cookie. Auto-derived as `true` when `NODE_ENV=production` or `FORCE_HTTPS=true`. Set to `false` only as an escape hatch for LAN testing without TLS — not recommended in production. | auto |
|
|
|
|
> **Warning:** `FORCE_HTTPS=true` without `TRUST_PROXY` set causes a redirect loop.
|
|
|
|
---
|
|
|
|
## OIDC / SSO
|
|
|
|
For setup instructions, see [OIDC-SSO](OIDC-SSO).
|
|
|
|
| Variable | Description | Default |
|
|
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
|
|
| `OIDC_ISSUER` | OpenID Connect provider URL (e.g. `https://auth.example.com`) | — |
|
|
| `OIDC_CLIENT_ID` | OIDC client ID | — |
|
|
| `OIDC_CLIENT_SECRET` | OIDC client secret | — |
|
|
| `OIDC_DISPLAY_NAME` | Label shown on the SSO login button | `SSO` |
|
|
| `OIDC_ONLY` | Force SSO-only mode: disables password login and registration, overrides Admin > Settings toggles, cannot be changed at runtime. First SSO login becomes admin on a fresh instance. | `false` |
|
|
| `OIDC_ADMIN_CLAIM` | OIDC claim used to identify admin users (e.g. `groups`) | — |
|
|
| `OIDC_ADMIN_VALUE` | Value of the OIDC claim that grants admin role (e.g. `app-trek-admins`) | — |
|
|
| `OIDC_SCOPE` | Space-separated OIDC scopes to request. **Fully replaces** the default — always include `openid email profile` plus any extra scopes (e.g. add `groups` when using `OIDC_ADMIN_CLAIM`) | `openid email profile` |
|
|
| `OIDC_DISCOVERY_URL` | Override the auto-constructed OIDC discovery endpoint. Required for providers with a non-standard path (e.g. Authentik) | — |
|
|
|
|
---
|
|
|
|
## WebAuthn / Passkeys
|
|
|
|
Passkey (WebAuthn) login is configured from the Admin panel, but the two cryptographically
|
|
sensitive values can be pinned via environment variables. Env vars take priority over the
|
|
corresponding database settings. These values are **only** ever derived from server-side config —
|
|
never from request `Host` / `X-Forwarded-Host` headers (mirroring OIDC redirect-URI handling).
|
|
|
|
| Variable | Description | Default |
|
|
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
|
|
| `WEBAUTHN_RP_ID` | Relying-Party ID — the registrable domain passkeys are bound to (e.g. `trek.example.com`). Overrides the `webauthn_rp_id` DB setting. When unset, it is derived from the hostname of `APP_URL`. Bare IP literals (IPv4/IPv6) are rejected. If it cannot be resolved, passkeys are disabled. | derived from `APP_URL` |
|
|
| `WEBAUTHN_ORIGINS` | Comma-separated list of allowed origins for passkey ceremonies (e.g. `https://trek.example.com`). Overrides the `webauthn_origins` DB setting; trailing slashes are stripped. When unset and the RP ID is not `localhost`, a single origin is derived from `APP_URL`. In dev (RP ID `localhost`) `http://localhost:5173` and `http://localhost:3001` are added automatically. | derived from `APP_URL` |
|
|
|
|
---
|
|
|
|
## Email / SMTP
|
|
|
|
SMTP settings can be configured via the Admin panel or overridden with environment variables. Env vars take priority
|
|
over the database values.
|
|
|
|
| Variable | Description | Default |
|
|
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------|
|
|
| `SMTP_HOST` | SMTP server hostname (e.g. `smtp.example.com`) | — |
|
|
| `SMTP_PORT` | SMTP server port. Port `465` enables implicit TLS (`secure: true`); all other ports use STARTTLS or plain. | — |
|
|
| `SMTP_USER` | SMTP authentication username | — |
|
|
| `SMTP_PASS` | SMTP authentication password | — |
|
|
| `SMTP_FROM` | Sender address for outbound emails (e.g. `TREK <noreply@example.com>`) | — |
|
|
| `SMTP_SKIP_TLS_VERIFY` | Set `true` to disable TLS certificate validation. Useful for self-signed certs on internal SMTP relays — not recommended in production. | `false` |
|
|
|
|
`SMTP_HOST`, `SMTP_PORT`, and `SMTP_FROM` are all required for email delivery to work. `SMTP_USER` and `SMTP_PASS` are
|
|
optional (for unauthenticated relays).
|
|
|
|
---
|
|
|
|
## Initial Setup
|
|
|
|
These variables only take effect on first boot, before any user exists.
|
|
|
|
| Variable | Description | Default |
|
|
|------------------|--------------------------------------|--------------------|
|
|
| `ADMIN_EMAIL` | Email for the first admin account | `admin@trek.local` |
|
|
| `ADMIN_PASSWORD` | Password for the first admin account | random |
|
|
|
|
Both variables must be set together. If either is omitted, the account is created with email `admin@trek.local` and a
|
|
randomly generated password that is printed to the server log. Once any user exists, these variables have no effect.
|
|
|
|
---
|
|
|
|
## MCP
|
|
|
|
For setup instructions, see [MCP-Overview](MCP-Overview).
|
|
|
|
| Variable | Description | Default |
|
|
|----------------------------|---------------------------------------------------------------------------------------------------------|---------|
|
|
| `MCP_RATE_LIMIT` | Max MCP API requests per user per minute | `300` |
|
|
| `MCP_MAX_SESSION_PER_USER` | Max concurrent MCP sessions per user. At the cap the user's least-recently-active session is closed to make room — requests are not rejected. | `20` |
|
|
| `MCP_SESSION_TTL` | Session idle timeout in seconds (max 86400) | `3600` |
|
|
| `MCP_SSE_KEEPALIVE` | SSE keep-alive ping interval in seconds — keeps the stream alive through reverse proxies. `0` disables the pings; an open stream still refreshes the session's idle timeout. | `25` |
|
|
|
|
---
|
|
|
|
## API Docs
|
|
|
|
| Variable | Description | Default |
|
|
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
|
|
| `TREK_API_DOCS_ENABLED` | Serve interactive OpenAPI/Swagger docs at `/api/docs` (raw spec at `/api/docs-json`). The spec enumerates every route including the admin surface, so it is off by default. | `false` |
|
|
|
|
With the flag on, `/api/docs` lists every REST endpoint with try-it-out; authorize with a session JWT
|
|
via the Bearer button (the API accepts `Authorization: Bearer <jwt>` everywhere as the cookie fallback).
|
|
Request bodies validated with Zod are documented automatically from the same schemas.
|
|
|
|
---
|
|
|
|
## Booking Import (KDE Itinerary)
|
|
|
|
| Variable | Description | Default |
|
|
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
|
|
| `KITINERARY_EXTRACTOR_PATH` | Full path to the `kitinerary-extractor` binary. When unset, TREK searches `/usr/lib/*/libexec/kf6/kitinerary-extractor` and then `PATH`. Set this if you install the binary to a non-standard location. | auto-detected |
|
|
|
|
The official TREK Docker image bundles the binary automatically: on amd64 it downloads the static release from
|
|
`https://cdn.kde.org/ci-builds/pim/kitinerary/`; on arm64 it installs `libkitinerary-bin` via apt (Debian trixie). When
|
|
running TREK from source, install `libkitinerary-bin` (Debian trixie / Ubuntu 25.04+) or download the static binary
|
|
directly and place it anywhere on `PATH`. The `GET /api/health/features` endpoint returns `{ "bookingImport": true }`
|
|
when the binary is found, and the Import button in the Reservations panel is hidden when it is not.
|
|
|
|
Booking import can also fall back to an AI model for documents KDE Itinerary can't read. That feature (the **AI Parsing** addon) is configured entirely in the UI and needs no environment variables — see [AI-Booking-Import](AI-Booking-Import).
|
|
|
|
---
|
|
|
|
## Public Transit (Transitous)
|
|
|
|
Public-transit routing in the planner is powered by [Transitous](https://transitous.org/), a free community MOTIS service — no API key is required. See [Transport: Flights, Trains, Cars](Transport-Flights-Trains-Cars) for the feature itself.
|
|
|
|
| Variable | Description | Default |
|
|
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
|
|
| `TRANSIT_API_URL` | Base URL of the transit routing API. TREK's server proxies requests to it. Point this at your own self-hosted [MOTIS](https://github.com/motis-project/motis) instance if you want zero third-party egress. A trailing slash is stripped. | `https://api.transitous.org` |
|
|
|
|
When left at the default, using the transit feature makes the TREK **server** send outbound HTTPS requests to `api.transitous.org` (with an identifying User-Agent, as the Transitous usage policy asks). No transit request is made until a user actually searches for a journey.
|
|
|
|
---
|
|
|
|
## Image Search (Unsplash)
|
|
|
|
TREK can search [Unsplash](https://unsplash.com/) for **trip cover images** and **place images**. By default the server queries Unsplash's public web endpoint **without an API key**, so no configuration is needed on most installs.
|
|
|
|
Some hosting environments — commonly VPS and datacenter IP ranges (and many Kubernetes clusters) — are **blocked or rate-limited** by that unauthenticated endpoint, which surfaces in the UI as **"Unsplash search unavailable"**. Configuring a free Unsplash Access Key switches the server to Unsplash's official, authenticated API (`api.unsplash.com`), which is not subject to that block. See [issue #1449](https://github.com/liketrek/TREK/issues/1449).
|
|
|
|
| Variable | Description | Default |
|
|
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|
|
|
| `UNSPLASH_ACCESS_KEY` | Unsplash **Access Key** used to authenticate cover/place image search against `https://api.unsplash.com`. When set, it takes priority over any key configured per-admin in **Admin → Settings**. When unset, the server falls back to the unauthenticated endpoint (which some datacenter/VPS IPs are blocked from). Get a free key at [unsplash.com/developers](https://unsplash.com/developers). | unauthenticated endpoint |
|
|
|
|
**Two ways to configure it** — pick one; the env var wins if both are present:
|
|
|
|
1. **Environment variable** (this page) — instance-wide, ideal for Docker/Helm/Unraid where you already manage config as env.
|
|
2. **Admin → Settings → API Keys** — paste the key into the **Unsplash API Key** field. Stored encrypted at rest and used as a fallback for every user when no env var is set. This is the better option if you'd rather not restart the container to change it.
|
|
|
|
To get a key: create a free account at [unsplash.com/developers](https://unsplash.com/developers), register a new application, and copy its **Access Key** (not the Secret Key). The Unsplash free tier (demo) allows 50 requests/hour, which is ample for cover search.
|
|
|
|
---
|
|
|
|
## Storage & Paths
|
|
|
|
Storage backends and category assignment are configured in
|
|
[[Admin: Storage|Admin-Storage]] (or a seed-once `storage-config.json`), not
|
|
through environment variables. `TREK_PLACE_PHOTO_DIR` below is unaffected.
|
|
|
|
| Variable | Description | Default |
|
|
|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|
|
|
| `TREK_PLACE_PHOTO_DIR` | Directory where cached Google place photos are stored. Created recursively on boot. Set this to point photo storage at a dedicated mounted volume. | `uploads/photos/google` |
|
|
| `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 log a warning and fall back to the default. | `500` |
|
|
| `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_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` |
|
|
|
|
### 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
|
|
file (`travel.db-shm`) and memory mapping, and [SQLite's own documentation](https://sqlite.org/wal.html#noshm) says that
|
|
combination is not safe on filesystems that don't implement those primitives properly. In practice that means Azure App
|
|
Service (Linux), and SMB/NFS volumes mounted from a NAS or a PaaS host. If your `data/` directory is one of those, set:
|
|
|
|
```
|
|
TREK_DB_JOURNAL_MODE=DELETE
|
|
```
|
|
|
|
The journal mode is written into the database file header, not held per connection, so it survives restarts and applies
|
|
from the next boot onward. The startup log prints what is actually in effect:
|
|
|
|
```
|
|
[DB] journal_mode=DELETE, synchronous=FULL
|
|
```
|
|
|
|
The maintenance tools that open the same file — `reset-admin.js` and `scripts/migrate-encryption.ts` — read the same two
|
|
variables, so run them with the same environment (`docker exec` into the container does this for you). Otherwise the
|
|
next key rotation or admin reset would quietly switch the file back to WAL.
|
|
|
|
---
|
|
|
|
## Advanced / Tuning
|
|
|
|
| Variable | Description | Default |
|
|
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
|
|
| `IDEMPOTENCY_TTL_SECONDS` | How long (in seconds) stored idempotency keys are kept before garbage collection. The offline client replays queued mutations with their `X-Idempotency-Key` on reconnect, so this must exceed the longest expected offline window or a replay could create a duplicate. Invalid values silently fall back to the default. | `2592000` (30 days) |
|
|
| `OVERPASS_URL` | Custom [Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API) endpoint(s) used by the map's POI "explore" search, comma-separated. When set it **replaces** the bundled public mirrors — point it at an internal or self-hosted Overpass instance when the public mirrors are unreachable from your network (e.g. firewalled/locked-down egress in a Kubernetes cluster). Entries that aren't valid `http(s)` URLs are ignored. If you don't run your own Overpass but the public mirrors throttle TREK, first make sure `APP_URL` (or `ALLOWED_ORIGINS`) is set: that alone gives outbound Overpass/Nominatim requests a unique User-Agent, which the public mirrors rate-limit far less. | bundled public mirrors |
|
|
| `OVERPASS_TIMEOUT_MS` | Per-endpoint timeout (in milliseconds) for Overpass POI requests. Endpoints race in parallel and one that hasn't answered within this window is abandoned so a faster mirror can win. Raise it if you run a slow self-hosted Overpass instance. Invalid values fall back to the default. | `12000` |
|
|
|
|
---
|
|
|
|
## Demo Mode
|
|
|
|
Demo mode runs TREK as a public, self-resetting sandbox. Not intended for regular deployments.
|
|
|
|
| Variable | Description | Default |
|
|
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
|
|
| `DEMO_MODE` | Enable demo mode: seeds example data, resets the database hourly, exposes the demo-login endpoint, and blocks destructive mutations (password change, account deletion, uploads) for demo users. Logs a security warning at startup if combined with `NODE_ENV=production`. | `false` |
|
|
| `DEMO_ADMIN_USER` | Username of the seeded demo admin account. | `admin` |
|
|
| `DEMO_ADMIN_EMAIL` | Email of the seeded demo admin account. | `admin@trek.app` |
|
|
| `DEMO_ADMIN_PASS` | Initial password for the seeded demo admin (bcrypt-hashed at seed time). | `admin12345` |
|
|
|
|
The `DEMO_ADMIN_*` variables only take effect when `DEMO_MODE=true`, and only at the moment the demo data is first
|
|
seeded.
|
|
|
|
---
|
|
|
|
## Plugins
|
|
|
|
The plugin system is **on by default**. The runtime and the Admin → Plugins panel are available out of the box, but installed plugins still have to be activated one by one — so no third-party code runs until an admin turns a specific plugin on. Set `TREK_PLUGINS_ENABLED=false` to switch the whole system off. See [Plugins](Plugins) for the full system and [Plugin-Permissions](Plugin-Permissions) for the isolation model.
|
|
|
|
| Variable | Description | Default |
|
|
|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
|
|
| `TREK_PLUGINS_ENABLED` | Master switch for the plugin system. Enabled unless set to `false` (also accepts `0`, `off`, `no`, case-insensitive). Turning it off is a kill switch — installed plugins stay on disk but nothing runs. | enabled |
|
|
| `TREK_PLUGINS_DIR` | Directory where installed plugin **code** is stored. Persist it as a volume if you use plugins. | `<data>/plugins` |
|
|
| `TREK_PLUGINS_DATA_DIR` | Directory for each plugin's own **data** (its private SQLite file). Kept separate from the code tree; persist it as a volume too. | `<data>/plugins-data` |
|
|
| `TREK_PLUGIN_REGISTRY_URL` | Override the plugin registry index the *Discover* tab browses. Point it at your own fork or mirror of the registry. | `https://raw.githubusercontent.com/liketrek/TREK-Plugins/main/dist/index.json` |
|
|
| `TREK_PLUGIN_MAX_RSS_MB` | Per-plugin memory ceiling in MB. A plugin process that exceeds it is stopped. | `300` |
|
|
| `TREK_PLUGIN_PERMISSIONS` | Set to `off` to opt **out** of the Node.js OS-level permission sandbox for plugin child processes (not recommended). Any other value keeps the sandbox on. | `on` |
|
|
| `TREK_PLUGIN_ALLOW_PRIVATE_EGRESS`| Set to `on` to let a plugin's declared outbound hosts resolve to private/internal addresses (e.g. a service on your LAN). By default connections to private, loopback, link-local and metadata addresses are refused. | off (private egress blocked) |
|
|
| `TREK_PLUGINS_DEV_LINK` | **Development only.** Set to exactly `1` to enable *dev-link*: registering a plugin from a local build directory and hot-reloading it against a live instance's data. Dev-linked code bypasses the install-time signature/integrity checks and (under `npm run dev`) runs with the OS permission jail off, so it must never be reachable in production — any value other than `1` (including absent) keeps it off. Data access is still fully gated by the capability host. | off (disabled) |
|
|
| `TREK_PLUGIN_AI_PER_DAY` | Per-plugin **daily** cap on shared-LLM broker calls (`ai.complete` / `ai.extract`). Bounds how much a single plugin can spend on the admin's LLM quota per UTC day, independent of its granted permissions. Counts persist across restarts within the same day; set to `0` to disable the AI broker entirely. Generous by design — only bites a runaway plugin. | `200` |
|
|
| `TREK_PLUGIN_NOTIFY_PER_DAY` | Per-plugin **daily** cap on user-notification broker calls (`notify.send`), so one plugin can't spam a user. Same UTC-day window and restart-safe counting as `TREK_PLUGIN_AI_PER_DAY`; set to `0` to disable the notify broker. | `100` |
|
|
| `TREK_PLUGIN_RPC_PER_SEC` | Sustained rate limit (calls **per second**) for a plugin's host RPC calls (`ctx.*`) once its burst allowance is spent. Prevents a tight-loop plugin from starving the single-threaded host. | `20` |
|
|
| `TREK_PLUGIN_RPC_BURST` | Burst allowance — how many host RPC calls a plugin may fire back-to-back before the per-second limit applies. | `60` |
|
|
| `TREK_PLUGIN_RPC_INFLIGHT` | Max concurrent host→plugin RPC dispatches allowed for a single plugin at once (concurrency cap). | `16` |
|
|
| `TREK_PLUGIN_AUDIT_MAX_ROWS` | Per-plugin retention cap for the capability audit log (kept in the shared `trek.db`). The newest N rows per plugin are retained and older ones pruned; the retained window stays tamper-evident. Set to `0` to disable pruning. | `20000` |
|
|
|
|
All of these are optional — the defaults are safe. Set `TREK_PLUGINS_ENABLED=false` if you want to switch the plugin system off entirely.
|
|
|
|
---
|
|
|
|
## Related Pages
|
|
|
|
- [Reverse-Proxy](Reverse-Proxy) — HTTPS proxy setup and the `FORCE_HTTPS` / `TRUST_PROXY` / `COOKIE_SECURE` trio
|
|
- [OIDC-SSO](OIDC-SSO) — complete OIDC configuration guide
|
|
- [MCP-Overview](MCP-Overview) — MCP server setup and rate limiting
|
|
- [Encryption-Key-Rotation](Encryption-Key-Rotation) — rotating the `ENCRYPTION_KEY` without losing data
|