TREK Docker Deployment Environment Variables: Complete Configuration Guide

TREK accepts over 40 environment variables via Docker to control server behavior, authentication, email delivery, and feature toggles, with defaults defined in charts/trek/values.yaml and full documentation maintained in the wiki/Environment-Variables.md file.

When deploying the mauriceboe/TREK travel management application in a containerized environment, you configure the application through environment variables passed via your docker run command, docker-compose.yml file, or Helm values. These variables govern everything from the HTTP port and encryption keys to SSO integration and MCP rate limits.

Core Server Configuration

TREK requires several fundamental variables to define how the Node.js server operates inside the container.

• PORT: The HTTP port the container listens on. Defaults to 3000 in Docker environments.
• HOST: The bind address. Only relevant for non-container installs (like Proxmox); containers default to all interfaces.
• NODE_ENV: Set to production or development. Defaults to production in container images.
• ENCRYPTION_KEY: At-rest encryption key for sensitive data. Auto-generated if omitted, but explicit assignment prevents key rotation issues.
• TZ: Server timezone. Defaults to UTC.
• LOG_LEVEL: Verbosity control, either info or debug. Defaults to info.
• DEFAULT_LANGUAGE: Default UI language code (e.g., en, de). Defaults to en.
• APP_URL: Public base URL (e.g., https://trek.example.com). Required for generating correct OIDC redirects and email links.

According to the source code in server/src/config.ts, the runtime resolution logic handles ENCRYPTION_KEY generation and validation when values are not explicitly provided.

Session and Security Settings

Control JWT lifetimes and cross-origin behavior with these variables.

• SESSION_DURATION: JWT lifetime when "Remember me" is unchecked. Defaults to 24h.
• SESSION_DURATION_REMEMBER: JWT lifetime when "Remember me" is checked. Defaults to 30d.
• ALLOWED_ORIGINS: CORS whitelist as comma-separated values. Defaults to same-origin.
• ALLOW_INTERNAL_NETWORK: Permit outbound calls to private IP ranges (e.g., for Immich integration). Defaults to false.

HTTPS and Reverse Proxy Configuration

When running TREK behind a reverse proxy like Nginx or Traefik, these variables ensure proper TLS handling and prevent redirect loops.

• FORCE_HTTPS: Enforces HTTPS, sets HSTS headers, and adds CSP upgrade-insecure-requests. Defaults to false.
• TRUST_PROXY: Number of trusted proxy hops; required for X-Forwarded-Proto parsing. Defaults to 1 in production.
• COOKIE_SECURE: Secure flag for the trek_session cookie. Auto-derived from FORCE_HTTPS if not set.
• HSTS_INCLUDE_SUBDOMAINS: Include sub-domains in the HSTS header. Defaults to false.

As documented in wiki/Reverse-Proxy.md, setting FORCE_HTTPS=true without a proper TRUST_PROXY value creates a redirect loop.

OpenID Connect (OIDC) and SSO

Enable single sign-on by configuring your identity provider.

• OIDC_ISSUER: Provider URL (e.g., https://auth.example.com).
• OIDC_CLIENT_ID and OIDC_CLIENT_SECRET: Credentials from your IdP.
• OIDC_DISPLAY_NAME: Button label on the login screen. Defaults to SSO.
• OIDC_ONLY: Disable local login and registration when set to true. Defaults to false.
• OIDC_ADMIN_CLAIM / OIDC_ADMIN_VALUE: Claim name and value that automatically grant admin privileges.
• OIDC_SCOPE: Space-separated scopes. Must include openid email profile. Defaults to openid email profile.
• OIDC_DISCOVERY_URL: Override the discovery endpoint if your provider uses a non-standard path.

WebAuthn and Passkeys

Configure hardware key and passkey authentication.

• WEBAUTHN_RP_ID: Relying-Party domain for passkeys. Derived from APP_URL if unset.
• WEBAUTHN_ORIGINS: Allowed origins for WebAuthn ceremonies. Derived from APP_URL if unset.

Email and SMTP Configuration

Required for password resets and notifications.

• SMTP_HOST: SMTP server hostname.
• SMTP_PORT: Port number. Port 465 implies implicit TLS.
• SMTP_USER / SMTP_PASS: Authentication credentials.
• SMTP_FROM: Sender address (e.g., TREK <noreply@example.com>).
• SMTP_SKIP_TLS_VERIFY: Disable TLS verification for self-signed certificates. Defaults to false.

Initial Admin Setup

These variables only apply on first boot when the database initializes.

• ADMIN_EMAIL: Email for the first admin account. Defaults to admin@trek.local.
• ADMIN_PASSWORD: Password for the first admin account. Defaults to a random generated value.

Advanced Features and Tuning

Configure specific TREK modules and performance characteristics.

Multi-Channel API (MCP)

• MCP_RATE_LIMIT: Maximum API requests per user per minute. Defaults to 300.
• MCP_MAX_SESSION_PER_USER: Maximum concurrent MCP sessions per user. Defaults to 20.

Booking Import

• KITINERARY_EXTRACTOR_PATH: Path to the kitinerary-extractor binary for KDE Itinerary parsing. Auto-detected if not specified.

Storage Paths

• TREK_PLACE_PHOTO_DIR: Directory for cached Google Place photos. Defaults to uploads/photos/google.
• BACKUP_UPLOAD_LIMIT_MB: Maximum size for uploaded restore archives. Defaults to 500.

Performance Tuning

• IDEMPOTENCY_TTL_SECONDS: TTL for stored idempotency keys. Defaults to 2592000 (30 days).
• OVERPASS_URL: Custom Overpass API endpoint(s) as comma-separated values. Defaults to bundled public mirrors.
• OVERPASS_TIMEOUT_MS: Per-endpoint timeout for Overpass requests. Defaults to 12000.

Demo Mode

Enable a sandbox environment for testing.

• DEMO_MODE: Enable demo sandbox with auto-reset and limited mutations. Defaults to false.
• DEMO_ADMIN_USER / DEMO_ADMIN_EMAIL / DEMO_ADMIN_PASS: Credentials for the seeded demo admin. Defaults to admin / admin@trek.app / admin12345.

Deployment Examples

Reference implementations for common container orchestration platforms are maintained in wiki/Install-Docker-Compose.md and charts/trek/values.yaml.

Docker Run

docker run -d \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e PORT=3000 \
  -e APP_URL=https://trek.example.com \
  -e FORCE_HTTPS=true \
  -e TRUST_PROXY=1 \
  -e SESSION_DURATION=24h \
  -e SESSION_DURATION_REMEMBER=30d \
  -e SMTP_HOST=smtp.example.com \
  -e SMTP_PORT=587 \
  -e SMTP_USER=mailer \
  -e SMTP_PASS=secret \
  -e SMTP_FROM="TREK <noreply@example.com>" \
  mauriceboe/trek:latest

Docker Compose

version: "3.8"
services:
  trek:
    image: mauriceboe/trek:latest
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      PORT: "3000"
      APP_URL: https://trek.example.com
      FORCE_HTTPS: "true"
      TRUST_PROXY: "1"
      SESSION_DURATION: 24h
      SESSION_DURATION_REMEMBER: 30d
      SMTP_HOST: smtp.example.com
      SMTP_PORT: "587"
      SMTP_USER: mailer
      SMTP_PASS: secret
      SMTP_FROM: "TREK <noreply@example.com>"
    restart: unless-stopped

Helm Values

env:
  NODE_ENV: production
  PORT: "3000"
  APP_URL: https://trek.example.com
  FORCE_HTTPS: "true"
  TRUST_PROXY: "1"
  SESSION_DURATION: 24h
  SESSION_DURATION_REMEMBER: 30d
  SMTP_HOST: smtp.example.com
  SMTP_PORT: "587"
  SMTP_USER: mailer
  SMTP_PASS: secret
  SMTP_FROM: "TREK <noreply@example.com>"

Summary

• TREK Docker deployment relies on environment variables defined in wiki/Environment-Variables.md and defaulted in charts/trek/values.yaml.
• Core variables include PORT, APP_URL, ENCRYPTION_KEY, and NODE_ENV for basic server operation.
• Security configuration requires careful tuning of FORCE_HTTPS, TRUST_PROXY, and COOKIE_SECURE when running behind reverse proxies.
• Authentication supports OIDC (OIDC_* variables) and WebAuthn (WEBAUTHN_* variables) for enterprise SSO and passkey login.
• Feature toggles like DEMO_MODE, MCP_RATE_LIMIT, and ALLOW_INTERNAL_NETWORK control specific application behaviors without code changes.

Frequently Asked Questions

What is the default port for TREK Docker containers?

TREK listens on port 3000 by default when running inside Docker. You can override this by setting the PORT environment variable, but ensure your container port mapping (-p flag or ports: section) matches this value.

How do I prevent redirect loops when forcing HTTPS?

Set both FORCE_HTTPS=true and TRUST_PROXY=1 (or higher, depending on your proxy chain length). The TRUST_PROXY variable tells TREK how many reverse proxy hops to trust when reading X-Forwarded-Proto headers. Without this configuration, the application enters a redirect loop as documented in wiki/Reverse-Proxy.md.

Where are encryption keys handled in TREK?

The ENCRYPTION_KEY variable defines at-rest encryption for sensitive data. If omitted, server/src/config.ts auto-generates a key on first boot. However, explicitly setting this value is recommended for production deployments to prevent key rotation issues during container restarts.

Can I disable local login and use only SSO?

Yes. Set OIDC_ONLY=true to disable local username/password authentication and registration forms. Ensure you have valid OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET values configured, or you will lock yourself out of the application.

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