docs: document all environment variables in docker-compose, .env.example, and README

Made-with: Cursor
2026-03-31 16:45:20 +03:00
parent 7522f396e7
commit ed8518aca4
3 changed files with 94 additions and 38 deletions
--- a/README.md
+++ b/README.md
@@ -125,11 +125,14 @@ services:
    environment:
      - NODE_ENV=production
      - PORT=3000
+      - TZ=UTC
+      - LOG_LEVEL=info
+      # - ALLOWED_ORIGINS=https://trek.example.com
      # - OIDC_ISSUER=https://auth.example.com
      # - OIDC_CLIENT_ID=trek
      # - OIDC_CLIENT_SECRET=supersecret
-      # - OIDC_DISPLAY_NAME="SSO"
-      # - OIDC_ONLY=true          # disable password auth entirely
+      # - OIDC_DISPLAY_NAME=SSO
+      # - OIDC_ONLY=false
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
@@ -226,17 +229,32 @@ trek.yourdomain.com {

 | Variable | Description | Default |
 |----------|-------------|---------|
+| **Core** | | |
 | `PORT` | Server port | `3000` |
-| `NODE_ENV` | Environment | `production` |
-| `JWT_SECRET` | JWT signing secret | Auto-generated |
-| `FORCE_HTTPS` | Redirect HTTP to HTTPS | `false` |
-| `OIDC_ISSUER` | OIDC provider URL | — |
+| `NODE_ENV` | Environment (`production` / `development`) | `production` |
+| `JWT_SECRET` | JWT signing secret; auto-generated and saved to `data/` if not set | Auto-generated |
+| `TZ` | Timezone for logs, reminders and cron jobs (e.g. `Europe/Berlin`) | `UTC` |
+| `LOG_LEVEL` | `info` = concise user actions, `debug` = verbose details | `info` |
+| `ALLOWED_ORIGINS` | Comma-separated origins for CORS and email links | same-origin |
+| `FORCE_HTTPS` | Redirect HTTP to HTTPS behind a TLS-terminating proxy | `false` |
+| `TRUST_PROXY` | Number of trusted reverse proxies for `X-Forwarded-For` | `1` |
+| **OIDC / SSO** | | |
+| `OIDC_ISSUER` | OpenID Connect provider URL | — |
 | `OIDC_CLIENT_ID` | OIDC client ID | — |
 | `OIDC_CLIENT_SECRET` | OIDC client secret | — |
-| `OIDC_DISPLAY_NAME` | SSO button label | `SSO` |
-| `OIDC_ONLY` | Disable password auth | `false` |
-| `TRUST_PROXY` | Trust proxy headers | `1` |
-| `DEMO_MODE` | Enable demo mode | `false` |
+| `OIDC_DISPLAY_NAME` | Label shown on the SSO login button | `SSO` |
+| `OIDC_ONLY` | Disable local password auth entirely (first SSO login becomes admin) | `false` |
+| **SMTP** | *Also configurable from Admin > Settings > Notifications* | |
+| `SMTP_HOST` | SMTP server hostname | — |
+| `SMTP_PORT` | SMTP port (`587` for STARTTLS, `465` for SSL) | — |
+| `SMTP_USER` | SMTP username | — |
+| `SMTP_PASS` | SMTP password | — |
+| `SMTP_FROM` | Sender address for notification emails | — |
+| `SMTP_SKIP_TLS_VERIFY` | Skip TLS certificate verification (self-signed certs) | `false` |
+| **Webhook** | *Also configurable from Admin > Settings > Notifications* | |
+| `NOTIFICATION_WEBHOOK_URL` | Discord or Slack webhook URL for notifications | — |
+| **Other** | | |
+| `DEMO_MODE` | Enable demo mode (hourly data resets) | `false` |

 ## Optional API Keys

@@ -261,6 +279,7 @@ docker build -t trek .

 - **Database**: SQLite, stored in `./data/travel.db`
 - **Uploads**: Stored in `./uploads/`
+- **Logs**: `./data/logs/trek.log` (auto-rotated)
 - **Backups**: Create and restore via Admin Panel
 - **Auto-Backups**: Configurable schedule and retention in Admin Panel

--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -17,14 +17,46 @@ services:
      - "3000:3000"
    environment:
      - NODE_ENV=production
-      - JWT_SECRET=${JWT_SECRET:-}
-      # ALLOWED_ORIGINS: restrict CORS + used as the app URL in email notification links
-      # If not set, same-origin CORS is used and email links default to http://localhost:PORT
-      - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-}
      - PORT=3000
+      # Auto-generated if not set; persist across restarts for stable sessions
+      - JWT_SECRET=${JWT_SECRET:-}
+      # Timezone for logs, reminders and scheduled tasks (e.g. Europe/Berlin)
      - TZ=${TZ:-UTC}
-      # LOG_LEVEL: info (default) or debug (verbose details in docker logs)
+      # info = concise user actions; debug = verbose admin-level details
      - LOG_LEVEL=${LOG_LEVEL:-info}
+      # Comma-separated origins for CORS and email notification links
+      - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-}
+      # Redirect HTTP to HTTPS when behind a TLS-terminating proxy
+      # - FORCE_HTTPS=true
+      # Number of trusted proxies (for X-Forwarded-For / real client IP)
+      # - TRUST_PROXY=1
+
+      ## ── OIDC / SSO ──────────────────────────────────────────────
+      # OpenID Connect provider URL
+      # - OIDC_ISSUER=https://auth.example.com
+      # - OIDC_CLIENT_ID=trek
+      # - OIDC_CLIENT_SECRET=supersecret
+      # Label shown on the SSO login button
+      # - OIDC_DISPLAY_NAME=SSO
+      # Set true to disable local password auth entirely (SSO only)
+      # - OIDC_ONLY=false
+
+      ## ── SMTP (email notifications) ──────────────────────────────
+      ## Can also be configured from Admin > Settings > Notifications
+      # - SMTP_HOST=smtp.example.com
+      # - SMTP_PORT=587
+      # - SMTP_USER=trek@example.com
+      # - SMTP_PASS=secret
+      # - SMTP_FROM=trek@example.com
+      # Skip TLS certificate verification (self-signed certs)
+      # - SMTP_SKIP_TLS_VERIFY=false
+
+      ## ── Webhook (Discord / Slack notifications) ─────────────────
+      ## Can also be configured from Admin > Settings > Notifications
+      # - NOTIFICATION_WEBHOOK_URL=https://discord.com/api/webhooks/...
+
+      ## ── Demo mode (resets data hourly) ──────────────────────────
+      # - DEMO_MODE=false
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
--- a/server/.env.example
+++ b/server/.env.example
@@ -1,34 +1,39 @@
-PORT=3000
+# ── Core ───────────────────────────────────────────────────────
+PORT=3001
 NODE_ENV=development
-DEBUG=false
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+TZ=UTC
+# info = concise user actions; debug = verbose admin-level details
 LOG_LEVEL=info

-# REQUIRED for production — generate with: openssl rand -hex 32
-JWT_SECRET=CHANGEME_GENERATE_WITH_openssl_rand_hex_32
-
-# Timezone (defaults to system timezone)
-# TZ=UTC
-
-# CORS — comma-separated origins (leave unset for same-origin in production, allow-all in development)
+# ── Networking ─────────────────────────────────────────────────
+# Comma-separated origins for CORS and email links
 # ALLOWED_ORIGINS=https://trek.example.com
-
-# Force HTTPS redirect (set to true behind TLS-terminating proxy)
-# FORCE_HTTPS=true
-
-# Trust proxy (set to number of proxy hops, e.g. 1 for single reverse proxy)
+# Redirect HTTP → HTTPS behind a TLS proxy
+# FORCE_HTTPS=false
+# Number of trusted proxies for X-Forwarded-For
 # TRUST_PROXY=1

-# Application URL (used for OIDC callback validation)
-# APP_URL=https://trek.example.com
-
-# Demo mode (enables demo login, disables registration)
-# DEMO_MODE=false
-
-# --- OIDC / SSO ---
+# ── OIDC / SSO ─────────────────────────────────────────────────
 # OIDC_ISSUER=https://auth.example.com
-# OIDC_CLIENT_ID=
-# OIDC_CLIENT_SECRET=
+# OIDC_CLIENT_ID=trek
+# OIDC_CLIENT_SECRET=supersecret
 # OIDC_DISPLAY_NAME=SSO
+# Disable local password auth entirely (SSO only)
 # OIDC_ONLY=false
 # OIDC_ADMIN_CLAIM=groups
 # OIDC_ADMIN_VALUE=app-trek-admins
+
+# ── SMTP (email notifications) ─────────────────────────────────
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_USER=trek@example.com
+# SMTP_PASS=secret
+# SMTP_FROM=trek@example.com
+# SMTP_SKIP_TLS_VERIFY=false
+
+# ── Webhook (Discord / Slack notifications) ────────────────────
+# NOTIFICATION_WEBHOOK_URL=https://discord.com/api/webhooks/...
+
+# ── Demo ───────────────────────────────────────────────────────
+# DEMO_MODE=false