mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-16 18:55:11 +00:00
chore: improve docker compose template, tests and docs (#11593)
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]>
This commit is contained in:
co-authored by
Mridang Agarwalla
parent
54095b64b1
commit
bac224c56d
@@ -28,6 +28,21 @@ You can either setup your environment for <a href={'#tls-mode-external'}>TLS mod
|
||||
|
||||
<ProxyGuideTLSMode components={props.components} mode="enabled" configfilename="enabled-tls.Caddyfile" configfilecontent={ConfigEnabled} providername={providername} link={link} lower={lower}></ProxyGuideTLSMode>
|
||||
|
||||
## Known issues
|
||||
|
||||
### TE: trailers header causes requests to hang
|
||||
|
||||
When a browser sends a `TE: trailers` HTTP header (common with HTTP/2), Caddy may forward it upstream where it conflicts with ZITADEL's gRPC-gateway handling.
|
||||
Requests that result in an error response will hang indefinitely instead of returning the error to the client.
|
||||
|
||||
**Workaround**: strip the header in Caddy before it reaches ZITADEL:
|
||||
|
||||
```
|
||||
reverse_proxy h2c://zitadel:8080 {
|
||||
header_up -TE
|
||||
}
|
||||
```
|
||||
|
||||
## More Information
|
||||
|
||||
<ProxyGuideMore components={props.components} ></ProxyGuideMore>
|
||||
|
||||
@@ -3,6 +3,36 @@ title: Reverse Proxy Configuration
|
||||
description: "Setup and configure reverse proxies like Traefik, NGINX, and Caddy to manage external traffic for self-hosted ZITADEL."
|
||||
---
|
||||
|
||||
ZITADEL exposes a single HTTP/2 port (default `8080`) that serves both gRPC and HTTP APIs, as well as the management console.
|
||||
Running a reverse proxy in front of ZITADEL is the recommended approach for production deployments because it:
|
||||
|
||||
- Terminates TLS and provides HTTPS to clients
|
||||
- Exposes standard ports (`80`/`443`) while keeping ZITADEL on an internal port
|
||||
- Handles certificate renewal (e.g. via Let's Encrypt)
|
||||
- Enables path-based routing between the ZITADEL API and the Login UI
|
||||
|
||||
## HTTP/2 and h2c requirements
|
||||
|
||||
ZITADEL relies on HTTP/2 for all gRPC communication.
|
||||
When the reverse proxy terminates TLS, it must forward traffic to ZITADEL using **h2c** (unencrypted HTTP/2), not HTTP/1.1.
|
||||
Not all reverse proxies support h2c by default — check the proxy-specific guides below for configuration examples.
|
||||
|
||||
For more details, see [HTTP/2 Support in ZITADEL](/self-hosting/manage/http2).
|
||||
|
||||
## TLS modes
|
||||
|
||||
ZITADEL supports three TLS modes that affect how the reverse proxy should be configured:
|
||||
|
||||
| Mode | Description | Typical use |
|
||||
|------|-------------|-------------|
|
||||
| `disabled` | ZITADEL listens on plain HTTP, reverse proxy handles nothing special | Local development, h2c passthrough |
|
||||
| `external` | ZITADEL listens on plain HTTP; reverse proxy terminates TLS | Most production setups |
|
||||
| `enabled` | ZITADEL itself terminates TLS (end-to-end encryption) | Environments requiring mutual TLS |
|
||||
|
||||
For more details, see [TLS Modes](/self-hosting/manage/tls_modes).
|
||||
|
||||
## Proxy guides
|
||||
|
||||
Check out one of the following guides to configure your favorite reverse proxy:
|
||||
|
||||
- [Traefik](/self-hosting/manage/reverseproxy/traefik)
|
||||
@@ -12,3 +42,14 @@ Check out one of the following guides to configure your favorite reverse proxy:
|
||||
- [Cloudflare](/self-hosting/manage/reverseproxy/cloudflare)
|
||||
- [Cloudflare Tunnel](/self-hosting/manage/reverseproxy/cloudflare_tunnel)
|
||||
- [Fronting Zitadel Cloud](/self-hosting/manage/reverseproxy/zitadel_cloud)
|
||||
|
||||
## Login UI routing
|
||||
|
||||
When running both the ZITADEL API and the Login V2 UI (`zitadel-login`) behind a reverse proxy, the proxy must route traffic to the correct upstream:
|
||||
|
||||
- `/ui/v2/login` → Login UI container (port `3000` by default)
|
||||
- All other paths → ZITADEL API container (port `8080` by default)
|
||||
|
||||
The proxy-specific guides include Docker Compose examples that demonstrate this split routing.
|
||||
|
||||
For tested proxy versions, see [ZITADEL Requirements](/self-hosting/manage/requirements#reverse-proxy).
|
||||
|
||||
Reference in New Issue
Block a user