Claude Fable 5
0629411966
Initial deliverable of the architecture phase: 16 ADRs (stack, CRDT collaboration, plugin sandbox, import/export, backups, CI/CD), data model, permission model, real-time collaboration and plugin concepts, deployment/operations/security documentation, and the milestone roadmap that the implementation issues are derived from. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
102 lines
4.7 KiB
Markdown
102 lines
4.7 KiB
Markdown
# 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)
|
|
|
|
```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.
|