feat(server): add TREK_UPLOADS_DIR env var for the uploads root

README.md

@@ -438,6 +438,7 @@ Caddy handles TLS and WebSockets automatically.
 | `TZ` | Timezone for logs, reminders and cron jobs (e.g. `Europe/Berlin`) | `UTC` |
 | `LOG_LEVEL` | `info` = concise user actions, `debug` = verbose details | `info` |
 | `TREK_WIKI_DIR` | Where the in-app Help pages (`/help`) read their content from. TREK ships its wiki and serves it from disk, so Help always matches the version you are running — you should not need to set this. Point it at your own directory to serve custom docs. If the path does not exist, Help falls back to fetching the public GitHub wiki (needs outbound network, and tracks the latest release). | bundled `wiki/` |
+| `TREK_UPLOADS_DIR` | Root directory for uploaded files (trip files, journey media, covers, avatars, place images, photo caches). Leave unset to keep the default `uploads/` directory next to the server — in Docker that is the `/app/uploads` volume. Set it to relocate uploads to another disk or mount; the path must be writable by the server. | `./uploads` |
 | `DEFAULT_LANGUAGE` | Default language on the login page for users with no saved preference. Browser/OS language is auto-detected first; this is the fallback. Supported: `de`, `en`, `es`, `fr`, `hu`, `nl`, `br`, `cs`, `pl`, `ru`, `zh`, `zh-TW`, `it`, `ar`, `id`, `tr`, `ja`, `ko`, `uk`, `gr` | `en` |
 | `ALLOWED_ORIGINS` | Comma-separated origins for CORS and email links | same-origin |
 | `FORCE_HTTPS` | Optional. When `true`: 301-redirects HTTP to HTTPS, sends HSTS, adds CSP `upgrade-insecure-requests`, forces the session cookie `secure` flag. Useful behind a TLS-terminating reverse proxy. Requires `TRUST_PROXY`. | `false` |

docker-compose.yml

@@ -22,6 +22,7 @@ services:
       - TZ=${TZ:-UTC} # Timezone for logs, reminders and scheduled tasks (e.g. Europe/Berlin)
       - LOG_LEVEL=${LOG_LEVEL:-info} # info = concise user actions; debug = verbose admin-level details
 #      - TREK_WIKI_DIR=/app/wiki # Where the in-app Help pages (/help) read their content from. Leave unset: the image ships the wiki at /app/wiki and finds it automatically. Only set this to serve your own docs, mounted into the container. If the path does not exist, Help falls back to fetching the public GitHub wiki (needs outbound network, and tracks the latest release rather than your version).
+#      - TREK_UPLOADS_DIR=/app/uploads # Root for uploaded files. Leave unset: this compose file already mounts ./uploads at /app/uploads and the image symlinks it into place. Only set this if you relocate uploads to a different mount (the path must be covered by a volume — the container filesystem is read-only).
 #      - DEFAULT_LANGUAGE=en # Default language on the login page for users with no saved preference. Browser/OS language is auto-detected first; this is the fallback. Supported: de, en, es, fr, hu, nl, br, cs, pl, ru, zh, zh-TW, it, ar
 #      - SESSION_DURATION=30d # How long users stay logged in (trek_session JWT + cookie maxAge). Accepts: 1h | 12h | 7d | 30d | 90d. Default: 24h
 #      - SESSION_DURATION_REMEMBER=30d # Session length when "Remember me" is ticked at login: longer-lived JWT + persistent cookie that survives browser restarts. Same format as SESSION_DURATION. Default: 30d

server/src/app-config/README.md

@@ -66,7 +66,8 @@ fallthrough and the strip-ALL-slashes quirk (see `parsers.ts`
 DI in Nest, module-top `readEnv()` consts elsewhere):
 PORT, HOST, TRUST_PROXY, SESSION_DURATION(_REMEMBER), MCP_SESSION_TTL,
 MCP_MAX_SESSION_PER_USER, MCP_SSE_KEEPALIVE, TREK_PLUGIN_RPC_*/LOG_*/MAX_RSS_MB,
-TREK_PLUGIN_REGISTRY_URL, TREK_WIKI_DIR*, TREK_PLACE_PHOTO_DIR, BACKUP_*,
+TREK_PLUGIN_REGISTRY_URL, TREK_WIKI_DIR*, TREK_PLACE_PHOTO_DIR,
+TREK_UPLOADS_DIR, BACKUP_*,
 TRANSIT_API_URL, LOG_LEVEL*, ALLOW_INTERNAL_NETWORK*, DEFAULT_LANGUAGE,
 TREK_DB_FILE, TREK_DB_JOURNAL_MODE, TREK_DB_SYNCHRONOUS, ENCRYPTION_KEY.
 (* frozen today because the consuming module captures it at import; tests that

server/src/app-config/derive.ts

@@ -257,6 +257,8 @@ export function derivePaths(raw: RawEnv) {
   return {
     wikiDir: raw.TREK_WIKI_DIR,
     placePhotoDir: raw.TREK_PLACE_PHOTO_DIR,
+    /** Uploads root override; unset keeps the computed `<server>/uploads` default (storage registry). */
+    uploadsDir: raw.TREK_UPLOADS_DIR,
   };
 }
 

server/src/app-config/env.schema.ts

@@ -124,6 +124,7 @@ export const envSchema = z.object({
   TREK_DB_SYNCHRONOUS: anyString,
   TREK_WIKI_DIR: anyString,
   TREK_PLACE_PHOTO_DIR: anyString,
+  TREK_UPLOADS_DIR: anyString,
   BACKUP_UPLOAD_LIMIT_MB: positiveNumber,
   BACKUP_MAX_DECOMPRESSED_MB: positiveNumber,
 

server/tests/unit/app-config/derive.test.ts

@@ -12,6 +12,7 @@ import {
   deriveIntegrations,
   deriveBackup,
   deriveNet,
+  derivePaths,
   deriveAll,
 } from '../../../src/app-config/derive';
 
@@ -221,6 +222,17 @@ describe('deriveNet', () => {
   });
 });
 
+describe('derivePaths', () => {
+  it('passes the path vars through raw — defaulting stays at the consumer', () => {
+    expect(derivePaths({ TREK_WIKI_DIR: '/w' }).wikiDir).toBe('/w');
+    expect(derivePaths({ TREK_PLACE_PHOTO_DIR: '/p' }).placePhotoDir).toBe('/p');
+    expect(derivePaths({ TREK_UPLOADS_DIR: '/mnt/uploads' }).uploadsDir).toBe('/mnt/uploads');
+    expect(derivePaths({}).uploadsDir).toBeUndefined();
+    expect(derivePaths({}).wikiDir).toBeUndefined();
+    expect(derivePaths({}).placePhotoDir).toBeUndefined();
+  });
+});
+
 describe('deriveAll', () => {
   it('assembles every namespace', () => {
     const env = deriveAll({ PORT: '4000', DEMO_MODE: 'true' });