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]>

deploy/compose/.env.example

@@ -0,0 +1,97 @@
+# ⚠️  INSECURE DEFAULTS — for local development only.
+# Before exposing this stack to a network, change ZITADEL_MASTERKEY,
+# POSTGRES_ADMIN_PASSWORD, and POSTGRES_ZITADEL_PASSWORD.
+# See: https://zitadel.com/docs/self-hosting/deploy/compose#homelab
+
+# -----------------------------
+# Domain and external URL
+# -----------------------------
+ZITADEL_DOMAIN=localhost
+# Used by the base (non-TLS) compose; TLS overlays also publish 80/443 and may still expose
+# this port unless their ports are adjusted.
+PROXY_HTTP_PUBLISHED_PORT=8080
+ZITADEL_EXTERNALPORT=8080
+ZITADEL_EXTERNALSECURE=false
+# Overridden by TLS overlays (they hardcode X-Forwarded-Proto: https).
+ZITADEL_PUBLIC_SCHEME=http
+
+# -----------------------------
+# Security/bootstrap
+# -----------------------------
+# Must be exactly 32 chars for new deployments.
+ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters
+LOGIN_CLIENT_PAT_EXPIRATION=2099-01-01T00:00:00Z
+
+# -----------------------------
+# Pinned image tags
+# To upgrade ZITADEL, bump ZITADEL_VERSION and run:
+#   docker compose --env-file .env -f docker-compose.yml pull
+#   docker compose --env-file .env -f docker-compose.yml up -d --wait
+# -----------------------------
+ZITADEL_VERSION=v4.11.0
+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
+
+# -----------------------------
+# Proxy settings
+# -----------------------------
+TRAEFIK_DASHBOARD_ENABLED=false
+TRAEFIK_LOG_LEVEL=INFO
+TRAEFIK_ACCESSLOG_ENABLED=true
+# Trusted proxy IPs for X-Forwarded-* headers (external-tls mode).
+# Comma-separated CIDR ranges of your upstream load balancer / reverse proxy.
+TRAEFIK_TRUSTED_IPS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+
+# Let's Encrypt mode
+LETSENCRYPT_EMAIL=[email protected]
+
+# -----------------------------
+# Postgres settings
+# -----------------------------
+POSTGRES_DB=zitadel
+POSTGRES_ADMIN_USER=postgres
+POSTGRES_ADMIN_PASSWORD=postgres
+POSTGRES_ZITADEL_USER=zitadel
+POSTGRES_ZITADEL_PASSWORD=zitadel
+
+# -----------------------------
+# Access logs
+# -----------------------------
+ZITADEL_ACCESS_LOG_STDOUT_ENABLED=true
+
+# -----------------------------
+# Optional Redis cache settings
+# Default is disabled.
+# Enable with --profile cache and switch connectors to redis.
+# -----------------------------
+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=
+
+# -----------------------------
+# Optional API tracing (OTEL)
+# Default is disabled. Enable with --profile observability.
+# The collector receives traces from ZITADEL on port 4317 (gRPC) and 4318 (HTTP)
+# and logs them to stdout by default.
+# To forward traces to your own backend (Grafana Tempo, Jaeger, OpenObserve, etc.),
+# uncomment the otlp exporter in otel-collector-config.yaml and set:
+# OTEL_BACKEND_ENDPOINT=http://your-backend:4317
+# -----------------------------
+ZITADEL_INSTRUMENTATION_SERVICENAME=zitadel-api
+ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_TYPE=none
+ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_ENDPOINT=otel-collector:4317
+ZITADEL_INSTRUMENTATION_TRACE_EXPORTER_INSECURE=true
+
+# -----------------------------
+# Future Login OTEL placeholders
+# Current login image may ignore these.
+# -----------------------------
+LOGIN_OTEL_SERVICE_NAME=zitadel-login
+LOGIN_OTEL_EXPORTER_OTLP_ENDPOINT=
+LOGIN_OTEL_EXPORTER_OTLP_PROTOCOL=grpc