TREK Environment Variables: Complete Configuration Guide for Advanced Deployment

TREK exposes extensive configuration options through environment variables defined in server/src/config.ts, covering everything from server ports and encryption keys to OIDC SSO and WebAuthn passkeys, with all variables documented in wiki/Environment-Variables.md.

The TREK travel planning platform (mauriceboe/TREK) centralizes its runtime configuration in a single configuration loader that reads directly from process.env. This architecture allows administrators to customize behavior without modifying source code, whether deploying via Docker Compose, Kubernetes Helm charts, or running from source with a local .env file.

Core Server Configuration

The core category controls fundamental runtime parameters including network binding, encryption, and localization. In server/src/config.ts, the server initializes these values at startup before binding to any port.

Key variables include:

• PORT – The HTTP server port (default: 3000).
• HOST – The bind address. Note: Only honored for non-container installations (Proxmox or source). Docker deployments should never set this, as container networking handles binding internally (lines 32-42).
• NODE_ENV – Runtime mode (development or production).
• ENCRYPTION_KEY – Primary symmetric key for session encryption. The server checks the environment first, then falls back to files data/.encryption_key → data/.jwt_secret → auto-generated key. This order guarantees that a manually supplied key is always persisted (lines 52-62).
• TZ – Server timezone (e.g., Europe/Berlin).
• LOG_LEVEL – Logging verbosity (debug, info, warn, error).
• DEFAULT_LANGUAGE – UI language code (e.g., de, en).
• SESSION_DURATION and SESSION_DURATION_REMEMBER – Session TTL values (e.g., 12h, 30d).
• ALLOWED_ORIGINS – CORS whitelist for the public base URL.
• INTERNAL_NETWORKS – IP ranges granted internal-network access privileges.

HTTPS and Reverse Proxy Settings

When running behind TLS-terminating reverse proxies like NGINX or Traefik, the HTTPS/Proxy category ensures secure cookie handling and protocol enforcement:

• FORCE_HTTPS – Enables HTTP to HTTPS redirection.
• HSTS_MAX_AGE – HTTP Strict Transport Security header duration.
• TRUST_PROXY – Number of trusted proxy hops (e.g., 2 for typical cloud load balancers).
• Cookie security flags – Automatically hardened when FORCE_HTTPS is enabled.

Authentication and Single Sign-On

TREK supports enterprise authentication through OIDC/SSO and passwordless WebAuthn/Passkeys:

OIDC Configuration

• OIDC_ISSUER – OpenID Connect provider discovery URL (e.g., https://auth.example.com).
• OIDC_CLIENT_ID and OIDC_CLIENT_SECRET – Service provider credentials.
• OIDC_ADMIN_CLAIM and OIDC_ADMIN_VALUE – Claims that elevate users to administrator status.
• OIDC_SCOPES – Requested scopes (default: openid profile email).

WebAuthn Configuration

• WEBAUTHN_RP_ID – Relying Party ID for passkey authentication.
• WEBAUTHN_ORIGINS – Allowed origins for passwordless login, overriding UI-derived defaults.

Email and SMTP Configuration

The Email/SMTP category enables password-reset flows and notifications:

• SMTP_HOST and SMTP_PORT – Mail server endpoint.
• SMTP_USER and SMTP_PASSWORD – Authentication credentials.
• SMTP_FROM – Sender address (e.g., TREK <noreply@example.com>).
• SMTP_SECURE and SMTP_VERIFY_CERT – TLS/SSL verification controls.

Advanced Tuning and Performance

For high-availability installations, the Advanced/Tuning and MCP (Multi-Channel Platform) categories provide fine-grained control:

• IDEMPOTENCY_TTL_SECONDS – Time-to-live for idempotency keys (default suitable for most deployments, but adjustable for long-running offline sync operations).
• OVERPASS_URL – Custom OpenStreetMap Overpass API endpoint.
• OVERPASS_TIMEOUT_MS – Query timeout for OSM data fetching (e.g., 20000 for 20 seconds on self-hosted Overpass servers).
• MCP_RATE_LIMIT – API request caps for shared installations.
• MCP_MAX_CONCURRENT_SESSIONS – Concurrent session limits for the MCP API.

Specialized Features and Paths

Additional variables control specific TREK features:

• Initial Setup – INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD bootstrap the first administrator account only on first boot.
• Booking Import – KITINERARY_EXTRACTOR_PATH points to the kitinerary-extractor binary for KDE Itinerary integration.
• Storage – PHOTO_CACHE_DIR and BACKUP_UPLOAD_MAX_SIZE manage disk usage for place photos and restore archives.
• Demo Mode – DEMO_MODE and related credentials enable the self-resetting sandbox instance.

Configuration Examples

Docker Compose Deployment

For containerized deployments, pass variables through the environment list or external .env files:

version: "3.8"
services:
  trek:
    image: ghcr.io/mauriceboe/trek:latest
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - NODE_ENV=production
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - TZ=Europe/Berlin
      - LOG_LEVEL=info
      - DEFAULT_LANGUAGE=de
      - SESSION_DURATION=12h
      - SESSION_DURATION_REMEMBER=30d
      - ALLOWED_ORIGINS=https://trek.example.com
      - TRUST_PROXY=2
      - FORCE_HTTPS=true
      - OIDC_ISSUER=https://auth.example.com
      - OIDC_CLIENT_ID=trek-app
      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OVERPASS_URL=https://overpass.example.com/api/interpreter

Kubernetes Helm Values

For Kubernetes deployments, inject variables through the Helm values file:

env:
  - name: IDEMPOTENCY_TTL_SECONDS
    value: "2592000"      # 30 days

  - name: OVERPASS_TIMEOUT_MS
    value: "20000"        # 20 s for self-hosted Overpass

  - name: MCP_RATE_LIMIT
    value: "500"
  - name: DEMO_MODE
    value: "false"

Source Deployment with .env

When running from source, TREK automatically loads a local .env file:

cat > .env <<EOF
PORT=3001
HOST=10.0.0.72
ENCRYPTION_KEY=my-secret-key
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_FROM=TREK <noreply@example.com>
OIDC_ISSUER=https://auth.example.com
OIDC_CLIENT_ID=trek
OIDC_CLIENT_SECRET=super-secret
EOF

npm run start

Summary

• TREK environment variables are defined in server/src/config.ts and documented in wiki/Environment-Variables.md, covering 11 functional categories from core networking to specialized features.
• The ENCRYPTION_KEY resolution follows a strict priority: environment variable → data/.encryption_key → data/.jwt_secret → auto-generated, ensuring deployment flexibility.
• HOST should only be set for bare-metal or Proxmox deployments; Docker containers handle networking internally.
• All variables are read from process.env, making TREK compatible with Docker Compose, Kubernetes, Helm, and traditional .env file workflows.

Frequently Asked Questions

How does TREK resolve the ENCRYPTION_KEY variable?

TREK checks for ENCRYPTION_KEY in the environment first, then falls back to files data/.encryption_key and data/.jwt_secret, finally auto-generating a key if none exist. This hierarchy, implemented in server/src/config.ts (lines 52-62), ensures that manually supplied keys are persisted while maintaining backward compatibility.

Should I set the HOST variable when running TREK in Docker?

No. The HOST variable is only honored for non-container installations such as Proxmox or direct source deployments. In Docker environments, container networking handles binding automatically, and setting HOST can cause connectivity issues (see server/src/config.ts, lines 32-42).

Where are TREK environment variables documented?

The canonical documentation resides in wiki/Environment-Variables.md within the repository. This file contains the complete reference for every supported variable, while server/src/config.ts contains the actual implementation logic that parses these values at runtime.

How do I configure OIDC SSO in TREK?

Set OIDC_ISSUER to your provider's discovery URL, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET to your service credentials, and optionally define OIDC_ADMIN_CLAIM and OIDC_ADMIN_VALUE to automatically elevate specific users to administrator status. These variables are processed during the authentication initialization phase in server/src/config.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}