zitadel/deploy/compose/AGENTS.md at fix-api-base-path

GitHub/zitadel

Fork 0

mirror of https://github.com/zitadel/zitadel.git synced 2026-07-25 18:28:00 +00:00

Files

T

bac224c56d 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 <mridang@zitadel.com>

2026-02-24 16:33:12 -08:00

3.9 KiB

Raw Permalink Blame History

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 for all user-facing text in any language

3.9 KiB Raw Permalink Blame History