Configuration

All Gatwy configuration is via environment variables. Everything has sensible defaults — only override what you need.

Environment Variables

Variable	Default	Description
PORT	7443	HTTPS listen port
GATWY_ENCRYPTION_KEY	(auto-generated file)	64-char hex AES-256 key for encrypting credentials and recordings. Set this in production.
ADMIN_PASSWORD	(none)	Pre-set admin password on first launch (skips the setup screen)
TLS_CERT_PATH	(auto)	Path to a custom TLS certificate inside the container
TLS_KEY_PATH	(auto)	Path to a custom TLS private key inside the container
DATA_DIR	/app/data	Directory for database, certs, recordings, and logs
BASE_PATH	(none)	URL path prefix (e.g. /gatwy) for deploying behind a reverse proxy that serves Gatwy under a sub-path

Encryption Key

Gatwy encrypts all credentials, MFA secrets, and session recordings using AES-256. The key can be provided two ways:

Option 1 — Environment Variable (Recommended)

GATWY_ENCRYPTION_KEY=$(openssl rand -hex 32)

The key lives outside the data volume, so a snapshot of /app/data alone is useless without it.

Option 2 — Auto-generated File (Fallback)

If the env var is not set, Gatwy creates a key at /app/data/encryption.key automatically. A red warning banner appears in the server logs and on the login page as a reminder.

warning

This is acceptable for home-lab use, but not recommended for production.

Key Rotation

If you switch from file-based to env-based key, export a backup first (Settings → Backup & Restore) and re-import after setting the new key — backups are self-contained and include the encryption key used.

Docker Compose Example

services:
  gatwy:
    image: ghcr.io/kotoxie/gatwy:latest
    container_name: gatwy
    restart: unless-stopped
    ports:
      - '7443:7443'
    volumes:
      - ./data:/app/data
    environment:
      - GATWY_ENCRYPTION_KEY=your-64-char-hex-key
      - ADMIN_PASSWORD=change-me-on-first-boot

TLS

By default Gatwy generates a self-signed certificate on first start. To use your own certificate, mount it into the container and point to it:

environment:
  - TLS_CERT_PATH=/app/certs/cert.pem
  - TLS_KEY_PATH=/app/certs/key.pem
volumes:
  - ./data:/app/data
  - ./certs:/app/certs:ro

tip

For production, a reverse proxy (Nginx, Caddy, Traefik) with Let's Encrypt is recommended. See the Reverse Proxy guide.

Path-Prefix Deployments

If your reverse proxy serves Gatwy under a sub-path instead of its own domain (e.g. https://example.com/gatwy/), set BASE_PATH so the UI, OIDC login, cookies, client-side routing, and Moonlight streaming all resolve correctly under that prefix:

environment:
  - BASE_PATH=/gatwy

See Reverse Proxy for a full example.

Custom Port

To run on a different port, change both the host binding and the PORT variable:

ports:
  - '8443:8443'
environment:
  - PORT=8443

Data Persistence

Gatwy stores all state — database, certificates, recordings, and logs — in the data directory. Always mount it to preserve data across container restarts:

volumes:
  - ./data:/app/data

Health Check

Gatwy exposes a health endpoint at /health:

curl -k https://localhost:7443/health

Add it to your Compose file:

healthcheck:
  test: ["CMD", "curl", "-fk", "https://localhost:7443/health"]
  interval: 30s
  timeout: 5s
  retries: 3