dorfteich/docs/architecture/deployment.md

Deployment architecture

Four stages, one Compose definition. Foundational decisions: ADR 0014 (CI/CD), ADR 0015 (backup), kickoff topology decision (Dev local; Test, Int, Prod on the LEISINGER host initially; Prod moves to a dedicated host at go-live).

The Compose stack

Every stage (and every self-hosted instance) runs the same services:

Service	Image	Notes
web	dorfteich-web	nginx: SPA assets, fonts; SPA fallback routing
api	dorfteich-api	NestJS; runs prisma migrate deploy on start
collab	dorfteich-collab	Hocuspocus WebSocket server
db	postgres:<pinned>	volume db-data
pandoc	pandoc/core:<pinned> (server mode)	internal only
gotenberg	gotenberg/gotenberg:<pinned>	internal only
backup	dorfteich-backup	cron sidecar: pg_dump, volume archive, prune, mirror (ADR 0015)

Volumes: db-data, uploads (uploads + installed plugins), backups. Networks: frontend (reverse proxy ↔ web/api/collab) and internal (api/collab ↔ db/pandoc/gotenberg); db and converters are never exposed.

Ingress is a host-level reverse proxy (existing Caddy/Traefik/nginx on the host), routing:

/            → web
/api/        → api
/collab      → collab   (WebSocket upgrade required)
/media/      → api      (permission-checked file streaming)

Self-hosters without a proxy can enable the optional caddy Compose profile (bundled Caddy with automatic TLS).

Stages

Stage	Where	Domain	Purpose	Data
Dev	contributor machine	localhost	feature work; hot reload via compose.dev.yml overlay (source mounts, vite dev server)	fixtures/seed script
Test	LEISINGER, /home/DOCKER/dorfteich-test/	dorfteich-test.101010.cloud	auto-deploy target of main; e2e suite runs here	reset-able; seeded
Int	LEISINGER, /home/DOCKER/dorfteich-int/	dorfteich-int.101010.cloud	stable preview; manual/exploratory testing; release candidates	persistent test data
Prod	LEISINGER initially → dedicated host at go-live	dorfteich.online	public flagship instance	real data; full backup + mirror

Stage layout follows the operator's Docker host convention: compose file + .env under /home/DOCKER/dorfteich-<stage>/, bulk data volumes under /home/RAID/DOCKER/dorfteich-<stage>/ (bind-mounted).

Prod relocation readiness (kickoff requirement): all state lives in the three volumes + .env; the documented move procedure is: stop stack → final backup → restore backup set on the new host → switch DNS. The backup sidecar's restore runbook doubles as the migration procedure, and Test restore drills (ADR 0015) keep it honest.

Configuration

• One .env per stage (never in git; .env.example in the repo documents every variable): database credentials, APP_BASE_URL, collab token signing key, SMTP settings, stage name shown in the UI for non-Prod.
• First-run setup wizard (kickoff decision): when the API starts against an empty database it exposes only /setup (create Site Admin account, SMTP, instance name/locale, registration mode); the wizard locks itself after completion. .env can pre-seed these for automated deploys (Test/Int use exactly that).

Pipeline (ADR 0014, concrete)

flowchart LR
    PR[PR: lint + typecheck + unit + build] -->|merge| M[main]
    M --> B[build images :sha]
    B --> DT[deploy Test]
    DT --> E2E[Playwright e2e vs Test]
    E2E -->|green| DI[deploy Int - tag int]
    DI --> REL{manual: tag vX.Y.Z + approval}
    REL --> DP[deploy Prod - semver tag]

• Deploy jobs SSH into the stage directory and run docker compose pull && docker compose up -d; migrations apply on api start. Rollback = re-deploy the previous tag (migrations must be backward-compatible one release back — contributor rule for schema stories).
• The e2e suite is the Int-promotion gate; flaky tests are defects.
• Release notes are generated from merged PR titles; releases with data-affecting migrations are labeled migration and called out.

Self-hosting distribution

• Published artifacts per release: versioned images in the Gitea registry (mirrored to a public registry at first public release), a reference docker-compose.yml + .env.example, and the install/update/backup guide (docs/self-hosting/, written as part of the docs milestone).
• Minimum requirements: Docker + Compose, 2 GB RAM, a domain (TLS via own proxy or the caddy profile). Setup = compose up + browser wizard.
• Updates: docker compose pull && up -d on a new semver tag; migrations run automatically; the release notes flag anything manual. Downgrades are supported one release back.