zitadel/deploy/compose/README.md

ZITADEL Docker Compose — Developer Reference

User-facing documentation: zitadel.com/docs/self-hosting/deploy/compose

This README is the contributor/developer reference — architecture decisions, file conventions, and routing logic.

Architecture

                 ┌─────────────────────────┐
  Browser ──────►│  Traefik (proxy)        │
                 │  Port 80 / 443          │
                 └───┬──────────┬──────────┘
                     │          │
          ┌──────────▼──┐  ┌───▼──────────┐
          │ zitadel-api  │  │ zitadel-login │
          │ Go :8080     │  │ Next.js :3000 │
          └──────┬───────┘  └──────────────┘
                 │
          ┌──────▼───────┐
          │  PostgreSQL   │
          └──────────────┘

Optional services via profiles: redis (cache), otel-collector (observability).

File Conventions

File	Role	Notes
docker-compose.yml	Base stack — all modes start from this	Must work standalone with .env.example
docker-compose.mode-letsencrypt.yml	TLS overlay: ACME HTTP challenge	Declares its own letsencrypt volume
docker-compose.mode-external-tls.yml	TLS overlay: upstream LB terminates TLS	Enables forwarded headers
docker-compose.mode-local-tls.yml	TLS overlay: self-signed certs	Mounts ./certs/ and traefik-local-tls.yml
docker-compose.prodlike.yml	Init/setup/start split	Uses YAML anchors for shared DB env
docker-compose.test.yml	CI smoke test overlay	Overrides images to :local tags
.env.example	User-facing config template	Copy to .env before first run
.env.test	CI-only config	Used by NX targets: test-run, test-e2e, test-full, stop
otel-collector-config.yaml	OTEL Collector pipeline config	Logs traces to stdout; configure OTEL_BACKEND_ENDPOINT to forward to a backend
traefik-local-tls.yml	Traefik dynamic config for local certs	Referenced by local-tls overlay
project.json	NX project definition	Targets: test-config, test-run, test-e2e, test, test-full, stop
AGENTS.md	AI agent instructions for this directory

Routing Rules

Traefik routes all traffic for ${ZITADEL_DOMAIN} via Docker labels:

Priority	Rule	Target	Middleware
400	Path(/)	zitadel-login	replacepath=/ui/v2/login/
250	PathPrefix(/ui/v2/login)	zitadel-login	—
200	PathPrefix(/api)	zitadel-api	stripprefix=/api
100	Everything else (OIDC, SAML, gRPC, gRPC-web, API v2 REST, ...)	zitadel-api (h2c)	—

No dedicated gRPC router is needed: Traefik's h2c backend scheme forwards gRPC and gRPC-web transparently. API v2 is served as REST/JSON via the gRPC-gateway at /v2/... paths.

Both web (HTTP) and websecure (HTTPS) entrypoints have identical router sets.

Why this routing model

• /api alias exists for DX — tools can use https://auth.example.com/api/...
• Canonical paths (e.g., /.well-known/openid-configuration, /oauth/v2/...) must remain at root for OIDC/SAML protocol compliance
• gRPC, gRPC-web, and REST all share the catch-all router — no separate gRPC router is needed because the h2c backend scheme makes Traefik forward all protocols transparently over HTTP/2

External Settings Invariant

ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT, and ZITADEL_EXTERNALSECURE must match the public URL that users see. If they don't, ZITADEL returns "Instance not found" errors. This is the single most common deployment issue.

Testing

Local NX targets for testing the compose stack:

Target	What it does	Requires Docker?
test-config	Validates all overlay combinations parse with docker compose config	No (just the CLI)
test-run	Builds local images (@zitadel/api:pack + @zitadel/login:pack), starts the stack with docker compose up --wait	Yes
test-e2e	Runs the full Playwright suite (wiring.spec.ts + smoke.spec.ts) against localhost:8888 through Traefik: per-service wiring checks (login, console, OIDC, SAML, API v1 REST, gRPC h2c, gRPC-web, API v2 REST HTTP/1.1 + HTTP/2) and the browser login flow	Yes (stack must be running)
test	Lightweight — delegates to test-config only. Safe for nx affected	No
test-full	Full pipeline: test-config → test-run → Playwright wiring + browser tests → teardown	Yes
stop	Tears down the zitadel-compose-test stack and removes volumes	Yes

Rejected Alternatives

Alternative	Why rejected
Strict /api-only rewrite	Breaks canonical protocol paths (OIDC, SAML)
/grpc path-prefix routing	gRPC clients/tools don't use path prefixes
Dedicated gRPC router (HeaderRegexp(Content-Type, ^application/grpc.*))	Redundant: h2c backend handles gRPC, gRPC-web, and Connect-RPC natively; the catch-all covers all three
Single container (API + Login)	Not aligned with v4 architecture; Login is a separate Next.js process
Merged TLS configs	Each TLS mode must remain independently composable
network_mode: service: for Login	Fragile, port conflicts, doesn't work with Traefik routing