mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
bac224c56d
Replaces the single-file `docker-compose.yaml` quickstart with a production-aware, Traefik-based compose pack in `deploy/compose/`. The pack covers the full arc from a 2-minute localhost quickstart to a hardened homelab or semi-production deployment. ### What's in the pack **Stack**: Traefik (proxy) → ZITADEL API (Go `:8080`) + ZITADEL Login (Next.js `:3000`) → PostgreSQL All HTTP/gRPC routing is handled by Traefik via Docker labels — no manual proxy config needed. The Login V2 UI is enabled by default. Login URLs are derived automatically from `ZITADEL_DOMAIN`, `ZITADEL_EXTERNALPORT`, and `ZITADEL_PUBLIC_SCHEME` — no separate URL variables needed. **Compose files** | File | Purpose | |------|---------| | `docker-compose.yml` | Base stack — works standalone. Uses explicit `name: zitadel` network for reliable Traefik service discovery. | | `docker-compose.mode-letsencrypt.yml` | TLS overlay: ACME HTTP challenge | | `docker-compose.mode-external-tls.yml` | TLS overlay: upstream LB/CDN terminates TLS. Uses `forwardedHeaders.trustedIPs` (configurable via `TRAEFIK_TRUSTED_IPS`) instead of `insecure=true`. | | `docker-compose.mode-local-tls.yml` | TLS overlay: self-signed certs for LAN | | `docker-compose.prodlike.yml` | Splits init / setup / start for controlled upgrades | | `docker-compose.test.yml` | CI overlay: swaps images to locally-built `:local` tags | **Optional profiles**: `cache` (Redis), `observability` (OpenTelemetry Collector) ### Build infra - New `@zitadel/api:pack` and `@zitadel/login:pack` Nx targets build local Docker images (`zitadel/zitadel:local`, `zitadel/zitadel-login:local`) for use in CI and local testing - `apps/api/Dockerfile` now accepts a `BINARY` build arg so local and release builds share the same image ### Testing - New `@zitadel/compose` Nx project with targets: `test-config` (validates all overlay combinations using `--quiet`), `test-run` (starts full stack with local images), `test-e2e` (Playwright wiring + protocol matrix tests through Traefik), `test-full` (end-to-end: build → start → test → teardown), `stop` - **`@zitadel/compose` is explicitly excluded from `nx affected` in CI for now** — the full stack smoke test requires a Docker daemon and significant resources. The intent is to add a dedicated `compose_smoke_test` CI job in a follow-up. The targets can be run locally with `pnpm nx run @zitadel/compose:test-full`. ### Documentation - **`compose.mdx`**: Complete rewrite with a staged structure (Stage 1 Quickstart → Stage 2 Homelab → Stage 3 Beyond Compose). Documents TLS modes, profiles, secrets hardening, ExternalDomain/Port/Secure invariant, upgrades, and the path to Kubernetes - **New `requirements.mdx`**: Lists supported PostgreSQL versions (14–18), Redis (standalone), Docker Compose v2.x, and reverse proxy h2c requirements - **`reverse_proxy.mdx`**: Added intro covering h2c requirements, TLS modes table, and Login UI routing split - **`troubleshooting.mdx`**: New sections for container restarts on upgrade, FIRSTINSTANCE env vars not taking effect, and diagnosing unhealthy containers - **`caddy/index.mdx`**: Known issue and workaround for the `TE: trailers` header hang - Removed the old `apps/docs/content/self-hosting/deploy/docker-compose.yaml` embedded in the docs ### Breaking change The old `apps/docs/content/self-hosting/deploy/docker-compose.yaml` file is deleted. The getting-started docs page (`/self-hosting/deploy/compose`) now points to the new pack via a `curl | tar` download command. --- ### Checklist - [x] `deploy/compose/` smoke test passes end-to-end locally (`pnpm nx run @zitadel/compose:test-full`) - [x] Docs build passes (`pnpm nx run @zitadel/docs:build`) - [ ] Follow-up issue created to add `compose_smoke_test` CI job --------- Co-authored-by: Mridang Agarwalla <[email protected]>
247 lines
10 KiB
YAML
247 lines
10 KiB
YAML
name: zitadel
|
|
|
|
services:
|
|
proxy:
|
|
image: ${TRAEFIK_IMAGE}
|
|
restart: unless-stopped
|
|
command:
|
|
- --providers.docker=true
|
|
- --providers.docker.exposedbydefault=false
|
|
- --providers.docker.network=zitadel
|
|
- --entrypoints.web.address=:80
|
|
- --entrypoints.websecure.address=:443
|
|
- --api.dashboard=${TRAEFIK_DASHBOARD_ENABLED}
|
|
- --api.insecure=false
|
|
- --ping=true
|
|
- --ping.entrypoint=web
|
|
- --log.level=${TRAEFIK_LOG_LEVEL}
|
|
- --accesslog=${TRAEFIK_ACCESSLOG_ENABLED}
|
|
ports:
|
|
- ${PROXY_HTTP_PUBLISHED_PORT}:80
|
|
networks:
|
|
- zitadel
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
depends_on:
|
|
zitadel-api:
|
|
condition: service_healthy
|
|
zitadel-login:
|
|
condition: service_healthy
|
|
|
|
zitadel-api:
|
|
image: ghcr.io/zitadel/zitadel:${ZITADEL_VERSION}
|
|
restart: unless-stopped
|
|
user: "0"
|
|
command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"
|
|
environment:
|
|
ZITADEL_PORT: 8080
|
|
ZITADEL_EXTERNALDOMAIN: ${ZITADEL_DOMAIN}
|
|
ZITADEL_EXTERNALPORT: ${ZITADEL_EXTERNALPORT}
|
|
ZITADEL_EXTERNALSECURE: ${ZITADEL_EXTERNALSECURE}
|
|
ZITADEL_TLS_ENABLED: false
|
|
|
|
ZITADEL_DATABASE_POSTGRES_HOST: postgres
|
|
ZITADEL_DATABASE_POSTGRES_PORT: 5432
|
|
ZITADEL_DATABASE_POSTGRES_DATABASE: ${POSTGRES_DB}
|
|
ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME: ${POSTGRES_ADMIN_USER}
|
|
ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD: ${POSTGRES_ADMIN_PASSWORD}
|
|
ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE: disable
|
|
ZITADEL_DATABASE_POSTGRES_USER_USERNAME: ${POSTGRES_ZITADEL_USER}
|
|
ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: ${POSTGRES_ZITADEL_PASSWORD}
|
|
ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE: disable
|
|
|
|
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false
|
|
ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH: /zitadel/bootstrap/login-client.pat
|
|
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME: login-client
|
|
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized IAM_LOGIN_CLIENT
|
|
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE: ${LOGIN_CLIENT_PAT_EXPIRATION}
|
|
|
|
ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: true
|
|
ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI: ${ZITADEL_PUBLIC_SCHEME}://${ZITADEL_DOMAIN}:${ZITADEL_EXTERNALPORT}/ui/v2/login/
|
|
ZITADEL_OIDC_DEFAULTLOGINURLV2: ${ZITADEL_PUBLIC_SCHEME}://${ZITADEL_DOMAIN}:${ZITADEL_EXTERNALPORT}/ui/v2/login/login?authRequest=
|
|
ZITADEL_OIDC_DEFAULTLOGOUTURLV2: ${ZITADEL_PUBLIC_SCHEME}://${ZITADEL_DOMAIN}:${ZITADEL_EXTERNALPORT}/ui/v2/login/logout?post_logout_redirect=
|
|
ZITADEL_SAML_DEFAULTLOGINURLV2: ${ZITADEL_PUBLIC_SCHEME}://${ZITADEL_DOMAIN}:${ZITADEL_EXTERNALPORT}/ui/v2/login/login?samlRequest=
|
|
|
|
ZITADEL_LOGSTORE_ACCESS_STDOUT_ENABLED: ${ZITADEL_ACCESS_LOG_STDOUT_ENABLED}
|
|
|
|
ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE: ${ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE}
|
|
ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_ENDPOINT: ${ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_ENDPOINT}
|
|
ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_INSECURE: ${ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_INSECURE}
|
|
ZITADEL_INSTRUMENTATION_SERVICENAME: ${ZITADEL_INSTRUMENTATION_SERVICENAME}
|
|
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_ENABLED: ${ZITADEL_CACHES_CONNECTORS_REDIS_ENABLED}
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_ADDR: ${ZITADEL_CACHES_CONNECTORS_REDIS_ADDR}
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_USERNAME: ${ZITADEL_CACHES_CONNECTORS_REDIS_USERNAME}
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_PASSWORD: ${ZITADEL_CACHES_CONNECTORS_REDIS_PASSWORD}
|
|
ZITADEL_CACHES_INSTANCE_CONNECTOR: ${ZITADEL_CACHES_INSTANCE_CONNECTOR}
|
|
ZITADEL_CACHES_MILESTONES_CONNECTOR: ${ZITADEL_CACHES_MILESTONES_CONNECTOR}
|
|
ZITADEL_CACHES_ORGANIZATION_CONNECTOR: ${ZITADEL_CACHES_ORGANIZATION_CONNECTOR}
|
|
|
|
healthcheck:
|
|
test:
|
|
- CMD
|
|
- /app/zitadel
|
|
- ready
|
|
interval: 10s
|
|
timeout: 30s
|
|
retries: 12
|
|
start_period: 20s
|
|
volumes:
|
|
- zitadel-bootstrap:/zitadel/bootstrap:rw
|
|
networks:
|
|
- zitadel
|
|
depends_on:
|
|
postgres:
|
|
condition: service_healthy
|
|
labels:
|
|
- traefik.enable=true
|
|
- traefik.docker.network=zitadel
|
|
|
|
- traefik.http.services.zitadel-api.loadbalancer.server.port=8080
|
|
- traefik.http.services.zitadel-api.loadbalancer.server.scheme=h2c
|
|
|
|
- traefik.http.middlewares.zitadel-strip-api.stripprefix.prefixes=/api
|
|
- traefik.http.middlewares.zitadel-strip-api.stripprefix.forceSlash=false
|
|
|
|
# Note: no dedicated gRPC router needed. All gRPC and Connect-RPC traffic
|
|
# is handled by the catch-all router below since the backend already uses h2c.
|
|
|
|
- traefik.http.routers.zitadel-api-alias-web.rule=Host(`${ZITADEL_DOMAIN}`) && PathPrefix(`/api`)
|
|
- traefik.http.routers.zitadel-api-alias-web.entrypoints=web
|
|
- traefik.http.routers.zitadel-api-alias-web.middlewares=zitadel-strip-api
|
|
- traefik.http.routers.zitadel-api-alias-web.service=zitadel-api
|
|
- traefik.http.routers.zitadel-api-alias-web.priority=200
|
|
|
|
- traefik.http.routers.zitadel-api-alias-websecure.rule=Host(`${ZITADEL_DOMAIN}`) && PathPrefix(`/api`)
|
|
- traefik.http.routers.zitadel-api-alias-websecure.entrypoints=websecure
|
|
- traefik.http.routers.zitadel-api-alias-websecure.tls=true
|
|
- traefik.http.routers.zitadel-api-alias-websecure.middlewares=zitadel-strip-api
|
|
- traefik.http.routers.zitadel-api-alias-websecure.service=zitadel-api
|
|
- traefik.http.routers.zitadel-api-alias-websecure.priority=200
|
|
|
|
- traefik.http.routers.zitadel-canonical-web.rule=Host(`${ZITADEL_DOMAIN}`) && !PathPrefix(`/ui/v2/login`) && !PathPrefix(`/api`) && !Path(`/`)
|
|
- traefik.http.routers.zitadel-canonical-web.entrypoints=web
|
|
- traefik.http.routers.zitadel-canonical-web.service=zitadel-api
|
|
- traefik.http.routers.zitadel-canonical-web.priority=100
|
|
|
|
- traefik.http.routers.zitadel-canonical-websecure.rule=Host(`${ZITADEL_DOMAIN}`) && !PathPrefix(`/ui/v2/login`) && !PathPrefix(`/api`) && !Path(`/`)
|
|
- traefik.http.routers.zitadel-canonical-websecure.entrypoints=websecure
|
|
- traefik.http.routers.zitadel-canonical-websecure.tls=true
|
|
- traefik.http.routers.zitadel-canonical-websecure.service=zitadel-api
|
|
- traefik.http.routers.zitadel-canonical-websecure.priority=100
|
|
|
|
zitadel-login:
|
|
image: ghcr.io/zitadel/zitadel-login:${ZITADEL_VERSION}
|
|
restart: unless-stopped
|
|
user: "0"
|
|
environment:
|
|
ZITADEL_API_URL: http://zitadel-api:8080
|
|
NEXT_PUBLIC_BASE_PATH: /ui/v2/login
|
|
ZITADEL_SERVICE_USER_TOKEN_FILE: /zitadel/bootstrap/login-client.pat
|
|
CUSTOM_REQUEST_HEADERS: Host:${ZITADEL_DOMAIN},X-Forwarded-Proto:${ZITADEL_PUBLIC_SCHEME}
|
|
|
|
# Future-ready placeholders for upcoming Login OTEL support.
|
|
OTEL_SERVICE_NAME: ${LOGIN_OTEL_SERVICE_NAME}
|
|
OTEL_EXPORTER_OTLP_ENDPOINT: ${LOGIN_OTEL_EXPORTER_OTLP_ENDPOINT}
|
|
OTEL_EXPORTER_OTLP_PROTOCOL: ${LOGIN_OTEL_EXPORTER_OTLP_PROTOCOL}
|
|
healthcheck:
|
|
test:
|
|
- CMD
|
|
- /bin/sh
|
|
- -c
|
|
- node /app/healthcheck.js http://localhost:3000/ui/v2/login/healthy
|
|
interval: 10s
|
|
timeout: 30s
|
|
retries: 12
|
|
start_period: 20s
|
|
volumes:
|
|
- zitadel-bootstrap:/zitadel/bootstrap:ro
|
|
networks:
|
|
- zitadel
|
|
depends_on:
|
|
zitadel-api:
|
|
condition: service_healthy
|
|
labels:
|
|
- traefik.enable=true
|
|
- traefik.docker.network=zitadel
|
|
- traefik.http.services.zitadel-login.loadbalancer.server.port=3000
|
|
|
|
- traefik.http.middlewares.zitadel-root-rewrite.replacepath.path=/ui/v2/login/
|
|
|
|
- traefik.http.routers.zitadel-root-web.rule=Host(`${ZITADEL_DOMAIN}`) && Path(`/`)
|
|
- traefik.http.routers.zitadel-root-web.entrypoints=web
|
|
- traefik.http.routers.zitadel-root-web.middlewares=zitadel-root-rewrite
|
|
- traefik.http.routers.zitadel-root-web.service=zitadel-login
|
|
- traefik.http.routers.zitadel-root-web.priority=400
|
|
|
|
- traefik.http.routers.zitadel-root-websecure.rule=Host(`${ZITADEL_DOMAIN}`) && Path(`/`)
|
|
- traefik.http.routers.zitadel-root-websecure.entrypoints=websecure
|
|
- traefik.http.routers.zitadel-root-websecure.tls=true
|
|
- traefik.http.routers.zitadel-root-websecure.middlewares=zitadel-root-rewrite
|
|
- traefik.http.routers.zitadel-root-websecure.service=zitadel-login
|
|
- traefik.http.routers.zitadel-root-websecure.priority=400
|
|
|
|
- traefik.http.routers.zitadel-login-web.rule=Host(`${ZITADEL_DOMAIN}`) && PathPrefix(`/ui/v2/login`)
|
|
- traefik.http.routers.zitadel-login-web.entrypoints=web
|
|
- traefik.http.routers.zitadel-login-web.service=zitadel-login
|
|
- traefik.http.routers.zitadel-login-web.priority=250
|
|
|
|
- traefik.http.routers.zitadel-login-websecure.rule=Host(`${ZITADEL_DOMAIN}`) && PathPrefix(`/ui/v2/login`)
|
|
- traefik.http.routers.zitadel-login-websecure.entrypoints=websecure
|
|
- traefik.http.routers.zitadel-login-websecure.tls=true
|
|
- traefik.http.routers.zitadel-login-websecure.service=zitadel-login
|
|
- traefik.http.routers.zitadel-login-websecure.priority=250
|
|
|
|
postgres:
|
|
image: ${POSTGRES_IMAGE}
|
|
restart: unless-stopped
|
|
environment:
|
|
POSTGRES_PASSWORD: ${POSTGRES_ADMIN_PASSWORD}
|
|
POSTGRES_USER: ${POSTGRES_ADMIN_USER}
|
|
POSTGRES_DB: ${POSTGRES_DB}
|
|
healthcheck:
|
|
test:
|
|
- CMD-SHELL
|
|
- pg_isready -d ${POSTGRES_DB} -U ${POSTGRES_ADMIN_USER}
|
|
interval: 10s
|
|
timeout: 30s
|
|
retries: 10
|
|
start_period: 20s
|
|
volumes:
|
|
- postgres-data:/var/lib/postgresql/data:rw
|
|
networks:
|
|
- zitadel
|
|
|
|
redis:
|
|
image: ${REDIS_IMAGE}
|
|
restart: unless-stopped
|
|
profiles:
|
|
- cache
|
|
command:
|
|
- --save
|
|
- ""
|
|
- --appendonly
|
|
- "no"
|
|
networks:
|
|
- zitadel
|
|
|
|
otel-collector:
|
|
image: ${OTEL_COLLECTOR_IMAGE}
|
|
restart: unless-stopped
|
|
profiles:
|
|
- observability
|
|
command:
|
|
- --config=/etc/otelcol/config.yaml
|
|
volumes:
|
|
- ./otel-collector-config.yaml:/etc/otelcol/config.yaml:ro
|
|
networks:
|
|
- zitadel
|
|
|
|
networks:
|
|
zitadel:
|
|
name: zitadel
|
|
|
|
volumes:
|
|
postgres-data:
|
|
zitadel-bootstrap:
|