Vaubaan Gateway
Docs menu

Install with Docker Compose

The reference Compose file runs the gateway, its data volume and a Caddy proxy that terminates TLS for your domain; it builds the gateway's image from the repository.

Steps

Needs Docker with Compose v2, a DNS name pointing at the host, ports 80 and 443 reachable, and Node.js for the key script.

git clone https://github.com/vaubaan/gateway.git
cd gateway
cp deploy/config/.env.example deploy/config/.env
cp deploy/config/gateway.example.yaml deploy/config/gateway.yaml
npm run gen-master-key     # prints the value for VAUBAAN_MASTER_KEY
openssl rand -hex 24       # prints a value for VAUBAAN_BOOTSTRAP_TOKEN

Edit deploy/config/.env: GATEWAY_DOMAIN, VAUBAAN_PUBLIC_URL (https, same host), VAUBAAN_ADMIN_EMAILS, and the two secrets above. Then:

docker compose --env-file deploy/config/.env -f deploy/compose.yaml up -d --build
curl -s https://your-domain/healthz

Then the first sign-in.

What to know

  • Pass --env-file deploy/config/.env on every Compose command (up, down, logs, config): Compose reads GATEWAY_DOMAIN from it and hands that one variable to the proxy. The proxy receives nothing else; the master key, the bootstrap token and the identity provider's secret go to the gateway container only. GATEWAY_DOMAIN must be the host of VAUBAAN_PUBLIC_URL; nothing checks it for you.
  • The YAML file wins over the environment, key by key, silently. gateway.example.yaml ships with every key commented out, so the copy changes nothing until you uncomment a key; uncomment only what you want the file to own and remove the twin variable from .env. Both files are gitignored.
  • Secrets go in through ${NAME} or ${file:/path} references in the YAML, or *_FILE variables.
  • Declare your proxy. deploy/config/.env.example sets VAUBAAN_TRUSTED_PROXIES to Docker's address pool, where the Caddy container lives; narrow it to your proxy. Without a trusted proxy the instance believes no client address: the per-address limits become one window shared by all callers and the activity records no address (it says so in one warning at start).
  • The gateway sets its own security headers; the proxy must not add or override them. The proxy must not buffer responses (the MCP door streams) nor cap request bodies under /git/ (a push streams through).

Everything about the image, running it without Compose, and the operations: deploy README.

Last changed 2026-10-16. This page as Markdown: /docs/install/docker-compose.md