# TREK Docker Deployment Environment Variables: Complete Configuration Guide

> Master TREK Docker deployment by understanding its 40+ environment variables for server control, authentication, and more. Configure your TREK instance effectively.

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

---

**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`](https://github.com/mauriceboe/TREK/blob/main/charts/trek/values.yaml) and full documentation maintained in the [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/wiki/Install-Docker-Compose.md) and [`charts/trek/values.yaml`](https://github.com/mauriceboe/TREK/blob/main/charts/trek/values.yaml).

### Docker Run

```bash
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

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

```yaml
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`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md) and defaulted in [`charts/trek/values.yaml`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.