mirror of
https://github.com/zitadel/zitadel.git
synced 2026-10-25 15:40:09 -05:00
Florian Forster
ef4db04533
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 <mridang@zitadel.com>
(cherry picked from commit bac224c56d)
95 lines
4.6 KiB
JSON
95 lines
4.6 KiB
JSON
{
|
|
"$schema": "../../node_modules/nx/schemas/project-schema.json",
|
|
"name": "@zitadel/compose",
|
|
"targets": {
|
|
"test-config": {
|
|
"description": "Validates that all compose file combinations parse correctly (no Docker daemon needed).",
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"cwd": "{projectRoot}",
|
|
"parallel": false,
|
|
"commands": [
|
|
"docker compose --env-file .env.example -f docker-compose.yml config --quiet",
|
|
"docker compose --env-file .env.example -f docker-compose.yml -f docker-compose.mode-letsencrypt.yml config --quiet",
|
|
"docker compose --env-file .env.example -f docker-compose.yml -f docker-compose.mode-external-tls.yml config --quiet",
|
|
"docker compose --env-file .env.example -f docker-compose.yml -f docker-compose.mode-local-tls.yml config --quiet",
|
|
"docker compose --env-file .env.example -f docker-compose.yml -f docker-compose.prodlike.yml config --quiet"
|
|
]
|
|
},
|
|
"inputs": [
|
|
"{projectRoot}/docker-compose.yml",
|
|
"{projectRoot}/docker-compose.mode-*.yml",
|
|
"{projectRoot}/docker-compose.prodlike.yml",
|
|
"{projectRoot}/.env.example"
|
|
]
|
|
},
|
|
"test-run": {
|
|
"description": "Starts the full compose stack using locally-built images. Waits until all containers are healthy before exiting.",
|
|
"dependsOn": [
|
|
"@zitadel/api:pack",
|
|
"@zitadel/login:pack"
|
|
],
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"cwd": "{projectRoot}",
|
|
"parallel": false,
|
|
"commands": [
|
|
"docker compose --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml -p zitadel-compose-test down --volumes --remove-orphans",
|
|
"docker compose --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml -p zitadel-compose-test up --force-recreate --wait"
|
|
]
|
|
}
|
|
},
|
|
"test-e2e": {
|
|
"description": "Runs the Playwright test suite (wiring.spec.ts + smoke.spec.ts) against the running compose stack via localhost:8888 through Traefik. Covers login, console, OIDC, SAML, API v1 REST, gRPC h2c, gRPC-web, API v2 REST (gRPC-gateway JSON) HTTP/1.1 and HTTP/2. Run 'pnpm exec playwright install chromium' once before using this target.",
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"cwd": "{projectRoot}",
|
|
"command": "pnpm exec playwright test --config playwright.config.ts"
|
|
},
|
|
"inputs": [
|
|
"{projectRoot}/playwright.config.ts",
|
|
"{projectRoot}/tests/**",
|
|
"{projectRoot}/.env.test",
|
|
"{projectRoot}/package.json"
|
|
]
|
|
},
|
|
"test": {
|
|
"description": "Lightweight test target safe for nx affected. Validates compose config syntax only (no Docker daemon needed).",
|
|
"dependsOn": [
|
|
"test-config"
|
|
]
|
|
},
|
|
"test-full": {
|
|
"description": "Builds local images, starts the compose stack, runs Playwright wiring tests (login, console, OIDC, SAML, API v1 REST, gRPC h2c, gRPC-web, API v2 REST HTTP/1.1 and HTTP/2) and the browser login smoke test through Traefik, then tears down.",
|
|
"dependsOn": [
|
|
"test-config",
|
|
"test-run"
|
|
],
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"cwd": "{projectRoot}",
|
|
"parallel": false,
|
|
"commands": [
|
|
"pnpm exec playwright install chromium",
|
|
"r=0; nx run @zitadel/compose:test-e2e || r=$?; nx run @zitadel/compose:stop; exit $r"
|
|
]
|
|
},
|
|
"inputs": [
|
|
"{projectRoot}/docker-compose.yml",
|
|
"{projectRoot}/docker-compose.test.yml",
|
|
"{projectRoot}/.env.test",
|
|
"{projectRoot}/playwright.config.ts",
|
|
"{projectRoot}/tests/**"
|
|
]
|
|
},
|
|
"stop": {
|
|
"description": "Tears down the compose smoke-test stack and removes all volumes.",
|
|
"executor": "nx:run-commands",
|
|
"options": {
|
|
"cwd": "{projectRoot}",
|
|
"command": "docker compose --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml -p zitadel-compose-test down --volumes"
|
|
}
|
|
}
|
|
}
|
|
}
|