Claude Fable 5
514cdf5ead
All checks were successful
CD / Build and push images (push) Successful in 3m45s
CI / Lint, typecheck, test (push) Successful in 3m39s
CI / Auth e2e pack (push) Successful in 3m43s
CI / Import/export fidelity gate (push) Successful in 43s
CI / Build container images (push) Has been skipped
CD / Deploy to Test (push) Successful in 9s
CD / Smoke tests against Test (push) Successful in 1m12s
CD / Promote to Int (push) Successful in 10s
Gitea itself relocated to the dedicated Hetzner server ONE (one.101010.cloud); this commit moves the rest of the delivery chain along: cd.yml now deploys to one.101010.cloud (DEPLOY_HOST_KEY secret rotated to ONE's host key), the act_runner one-dorfteich replaces vps-dorfteich, and the stage/deployment docs describe the new topology (Test/Int migrated with volumes; Prod joins on the same host at M8). The Int promotion gate variable RUN_INT_DEPLOY was removed — the new host has the capacity, so promote-int deploys again by default. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
110 lines
6.4 KiB
Markdown
110 lines
6.4 KiB
Markdown
# Deployment architecture
|
|
|
|
Four stages, one Compose definition. Foundational decisions: ADR 0014
|
|
(CI/CD), ADR 0015 (backup), kickoff topology decision (Dev local on the
|
|
developer's machine; Test, Int and — from M8 — Prod on the operator's
|
|
dedicated Hetzner server ONE (`one.101010.cloud`, 168.119.32.247), which
|
|
also hosts the Gitea instance and the CI runner; the architecture must
|
|
keep any later move cheap). DNS status: `*.dorfteich.online` and
|
|
`*.dorfteich.cloud` already point to ONE. (Until 2026-07-11 the stages
|
|
ran on a shared 4-GB VPS, `188.245.116.44`.)
|
|
|
|
## 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)
|
|
```
|
|
|
|
The proxy forwards `/collab` without stripping the prefix, so the collab
|
|
service answers its health probe at `/collab/healthz` externally and at
|
|
`/healthz` for the container-internal Docker healthcheck.
|
|
|
|
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 (e.g. the operator's MacBook), Docker Desktop | `localhost` | feature work; hot reload via `compose.dev.yml` overlay (source mounts, vite dev server) | fixtures/seed script |
|
|
| **Test** | ONE `one.101010.cloud`, `/home/DOCKER/dorfteich-test/` | `test.dorfteich.cloud` | auto-deploy target of `main`; e2e suite runs here | reset-able; seeded |
|
|
| **Int** | ONE `one.101010.cloud`, `/home/DOCKER/dorfteich-int/` | `int.dorfteich.cloud` | stable preview; manual/exploratory testing; release candidates | persistent test data |
|
|
| **Prod** | ONE `one.101010.cloud`, `/home/DOCKER/dorfteich-prod/` (M8, #89) | `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)
|
|
|
|
```mermaid
|
|
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.
|