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]>
64 lines
3.9 KiB
Markdown
64 lines
3.9 KiB
Markdown
## Docker Compose Deployment — AI Agent Instructions
|
|
|
|
### 1. Scope & Architecture
|
|
|
|
This directory provides a production-aware single-node Docker Compose deployment for ZITADEL.
|
|
The stack contains four core services and two optional profile-based services:
|
|
|
|
- **Core:** `zitadel-api` (Go API), `zitadel-login` (Next.js Login UI), `postgres`, `proxy` (Traefik)
|
|
- **Optional:** `redis` (cache profile), `otel-collector` (observability profile)
|
|
|
|
### 2. File Conventions
|
|
|
|
| File | Purpose | Safe to modify? |
|
|
|------|---------|----------------|
|
|
| `docker-compose.yml` | Base stack — all modes start from this | Yes, with care |
|
|
| `docker-compose.mode-*.yml` | TLS mode overlays (one per mode) | Yes |
|
|
| `docker-compose.prodlike.yml` | Init/setup/start split overlay | Yes |
|
|
| `docker-compose.test.yml` | CI test overlay (local images, no direct ports) | Yes |
|
|
| `.env.example` | User-facing config template | Yes — update on version bumps |
|
|
| `.env.test` | CI-only test config | Internal only |
|
|
| `otel-collector-config.yaml` | OTEL Collector pipeline config | Yes |
|
|
| `traefik-local-tls.yml` | Traefik dynamic config for local TLS certs | Yes |
|
|
| `project.json` | NX project definition | Auto-managed by NX |
|
|
| `README.md` | Developer/contributor reference | Yes |
|
|
|
|
### 3. Key Invariants
|
|
|
|
- **Four TLS modes must remain independently composable.** Never merge mode-specific config into the base `docker-compose.yml`. Each `docker-compose.mode-*.yml` overlay must work when composed with the base file alone.
|
|
- **gRPC routing uses `Content-Type: application/grpc*` header matching**, not path prefixes. Do NOT introduce `/grpc` path routing.
|
|
- **`ZITADEL_EXTERNALDOMAIN`, `ZITADEL_EXTERNALPORT`, `ZITADEL_EXTERNALSECURE` must be consistent** with the actual public endpoint. Mismatches cause "Instance not found" errors — the single most common deployment issue.
|
|
- **Profiles (`cache`, `observability`) are opt-in** and must not affect the default stack behavior.
|
|
- **The `/api` path alias coexists with canonical ZITADEL paths.** Do NOT remove canonical root-level path routing (e.g., `/.well-known/`, `/oauth/v2/`). The `/api` prefix is a convenience alias.
|
|
- **Image versions are pinned in `.env.example`** via `ZITADEL_VERSION` and infrastructure image variables. When bumping versions, update `.env.example`.
|
|
- **CI tests must go through Traefik.** The test overlay must NOT expose direct container ports. All smoke test traffic flows through the proxy to validate routing end-to-end.
|
|
|
|
### 4. Rejected Alternatives
|
|
|
|
These designs were considered and explicitly rejected — do not re-propose them:
|
|
|
|
- **Single container** merging API + Login — not aligned with v4 architecture
|
|
- **`/grpc` path-prefix routing** — tool/client incompatibility risk
|
|
- **Strict `/api`-only rewrite model** — breaks canonical OIDC/SAML protocol paths
|
|
- **`network_mode: service:`** for Login — fragile, port conflicts, incompatible with Traefik routing
|
|
- **Merged TLS configurations** — each mode must be independently composable without side effects
|
|
|
|
### 5. Common Commands
|
|
|
|
| Task | Command |
|
|
|------|---------|
|
|
| Start (local dev) | `cp .env.example .env && docker compose up -d --wait` |
|
|
| Start (Let's Encrypt) | `docker compose --env-file .env -f docker-compose.yml -f docker-compose.mode-letsencrypt.yml up -d --wait` |
|
|
| Start (production-like) | `docker compose --env-file .env -f docker-compose.yml -f docker-compose.prodlike.yml up -d --wait` |
|
|
| Validate all configs | `docker compose --env-file .env.example -f docker-compose.yml -f <overlay> config > /dev/null` for each overlay |
|
|
| Run CI smoke test | `pnpm nx run @zitadel/compose:test-full` |
|
|
| Smoke check | `curl -sS http://localhost:8888/.well-known/openid-configuration` |
|
|
|
|
### 6. Terminology
|
|
|
|
Follow the root `AGENTS.md` glossary. Key rules:
|
|
|
|
- **Instance** = a logical ZITADEL tenant/partition, NEVER "example"
|
|
- **System** = the entire ZITADEL installation/deployment
|
|
- See the [Technical Glossary](../../AGENTS.md) for all user-facing text in any language
|