Skip to content

GateKeeper uses a two-tier configuration model:

  • Env vars - infrastructure settings that require a container restart to change. Keep these minimal.
  • Admin UI - everything else. Changes take effect immediately with no restart.

Required env vars ​

VariableExampleDescription
BASE_URLhttps://auth.example.comPublic URL. Used as the OIDC issuer and WebAuthn origin. No trailing slash.
SECRET_KEY64 hex charsAt least 32 characters. Encrypts TOTP secrets and signs sessions. Do not change after first run without revoking all sessions.

Generate a secret key:

bash
openssl rand -hex 32

Optional env vars ​

VariableDefaultDescription
PORT8282Public HTTP port (login, OIDC, ForwardAuth)
ADMIN_PORT8283Admin-only HTTP port, served at the root. Keep it off the public internet.
ADMIN_URL-Public URL of the admin panel when it runs on its own subdomain, e.g. https://admin.auth.example.com. Enables admin passkeys.
ADMIN_BASE_PATH-Serve the admin under a path prefix (e.g. /admin) instead of the root. Leave empty when the admin has its own domain.
REDIRECT_ALLOWED_HOSTS-Comma-separated hosts (or .domain suffixes) users may be redirected to after login, for apps outside COOKIE_DOMAIN
DB_PATH/data/gatekeeper.dbSQLite database path. Mount a volume here.
COOKIE_DOMAIN-Cookie domain for cross-subdomain session sharing, e.g. .example.com
LOG_LEVELinfodebug, info, warn, or error

Env var fallbacks (overridden by admin UI) ​

These can be set as defaults via env vars, but any value saved in the admin UI takes precedence. If you set them here, they show up pre-filled in the settings form.

VariableDefaultDescription
SMTP_HOST-SMTP server hostname
SMTP_PORT587SMTP port
SMTP_USERNAME-SMTP username
SMTP_PASSWORD-SMTP password
SMTP_FROM-From address for outgoing emails
SMTP_TLSstarttlsstarttls, tls, or none
SESSION_TTL_HOURS8Session lifetime in hours
ALLOWED_EMAIL_DOMAINS-Comma-separated allowed domains, empty = all

Settings managed in the admin UI ​

Go to /settings on your admin panel to configure:

  • Allowed email domains - restrict which email addresses can log in. Leave blank to allow all.
  • Session timeout - how many hours before an idle session expires.
  • SMTP - all mail server settings.

Changes to these settings apply immediately to all new requests, with no restart needed.

Minimal compose file ​

yaml
services:
  gatekeeper:
    image: ghcr.io/chr0nzz/gatekeeper:latest
    environment:
      BASE_URL: "https://auth.example.com"
      SECRET_KEY: "your-secret-key-here"
    volumes:
      - gatekeeper_data:/data

volumes:
  gatekeeper_data: