mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05: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]>
66 lines
2.2 KiB
Bash
66 lines
2.2 KiB
Bash
# Test environment for NX smoke tests.
|
|
# Used with docker-compose.test.yml overlay to run locally-built images.
|
|
# Do NOT use for production deployments.
|
|
|
|
ZITADEL_DOMAIN=localhost
|
|
PROXY_HTTP_PUBLISHED_PORT=8888
|
|
ZITADEL_EXTERNALPORT=8888
|
|
ZITADEL_EXTERNALSECURE=false
|
|
ZITADEL_PUBLIC_SCHEME=http
|
|
|
|
ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters
|
|
LOGIN_CLIENT_PAT_EXPIRATION=2099-01-01T00:00:00Z
|
|
|
|
# Suppresses interpolation warnings from the base compose file.
|
|
# The actual image tags for zitadel-api and zitadel-login are overridden
|
|
# by docker-compose.test.yml to use locally-built :local tags.
|
|
ZITADEL_VERSION=local
|
|
|
|
# Images for services not overridden by docker-compose.test.yml
|
|
TRAEFIK_IMAGE=traefik:v3.6.8
|
|
POSTGRES_IMAGE=postgres:17.2-alpine
|
|
REDIS_IMAGE=redis:7.4.2-alpine
|
|
OTEL_COLLECTOR_IMAGE=otel/opentelemetry-collector-contrib:0.114.0
|
|
|
|
# Traefik
|
|
TRAEFIK_DASHBOARD_ENABLED=false
|
|
TRAEFIK_LOG_LEVEL=ERROR
|
|
TRAEFIK_ACCESSLOG_ENABLED=false
|
|
TRAEFIK_TRUSTED_IPS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
|
|
|
|
# Postgres
|
|
POSTGRES_DB=zitadel
|
|
POSTGRES_ADMIN_USER=postgres
|
|
POSTGRES_ADMIN_PASSWORD=postgres
|
|
POSTGRES_ZITADEL_USER=zitadel
|
|
POSTGRES_ZITADEL_PASSWORD=zitadel
|
|
|
|
# Disable access logs to reduce noise in test output
|
|
ZITADEL_ACCESS_LOG_STDOUT_ENABLED=false
|
|
|
|
# Tracing disabled
|
|
ZITADEL_INSTRUMENTATION_SERVICENAME=zitadel-api
|
|
ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE=none
|
|
ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_ENDPOINT=
|
|
ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_INSECURE=false
|
|
|
|
# Cache disabled (no Redis profile)
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_ENABLED=false
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_ADDR=redis:6379
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_USERNAME=
|
|
ZITADEL_CACHES_CONNECTORS_REDIS_PASSWORD=
|
|
ZITADEL_CACHES_INSTANCE_CONNECTOR=
|
|
ZITADEL_CACHES_MILESTONES_CONNECTOR=
|
|
ZITADEL_CACHES_ORGANIZATION_CONNECTOR=
|
|
|
|
# Playwright smoke test credentials.
|
|
# SMOKE_TEST_ADMIN_USERNAME must match ZITADEL's initial admin login name:
|
|
# <username>@<org-domain>.<external-domain> → [email protected]
|
|
SMOKE_TEST_ADMIN_USERNAME=[email protected]
|
|
SMOKE_TEST_ADMIN_PASSWORD=Password1!
|
|
|
|
# Login OTEL disabled
|
|
LOGIN_OTEL_SERVICE_NAME=zitadel-login
|
|
LOGIN_OTEL_EXPORTER_OTLP_ENDPOINT=
|
|
LOGIN_OTEL_EXPORTER_OTLP_PROTOCOL=grpc
|