# TREK Environment Variables: Complete Configuration Guide for Advanced Deployment

> Master advanced TREK deployment with our complete guide to TREK environment variables. Configure ports, encryption, SSO, passkeys, and more. Discover all options in server/src/config.ts.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-04

---

**TREK exposes extensive configuration options through environment variables defined in [`server/src/config.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md).**

The TREK travel planning platform ([mauriceboe/TREK](https://github.com/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`](https://github.com/mauriceboe/TREK/blob/main/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:

```yaml
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:

```yaml
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:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/server/src/config.ts) and documented in [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/config.ts), lines 32-42).

### Where are TREK environment variables documented?

The canonical documentation resides in [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md) within the repository. This file contains the complete reference for every supported variable, while [`server/src/config.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/config.ts).