Claude Fable 5 6517c8fb71 Update topology: non-prod stages on the VPS, Prod host decided at go-live

Kickoff update by the project owner: test.dorfteich.cloud and
int.dorfteich.cloud run on the VPS 188.245.116.44 (DNS for
*.dorfteich.cloud and *.dorfteich.online already points there); the
Prod host for dorfteich.online is chosen at go-live. Dev runs locally
via Docker. Affects deployment.md, roadmap.md, and ADR 0014; the
matching Gitea issues (#8, #9, #87, #89) were updated in place.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-04 15:20:58 +02:00

2.8 KiB

Raw Blame History

ADR 0014: CI/CD with Gitea Actions, staged promotion

Status: accepted
Date: 2026-07-04

Context

The project is hosted on a self-managed Gitea (gitea.101010.cloud). Environments (kickoff): Dev runs locally on contributors' machines; Test and Int run as separate Compose stacks on the operator's VPS (188.245.116.44, domains test.dorfteich.cloud / int.dorfteich.cloud); the Prod host (dorfteich.online) is decided at go-live — the VPS or a dedicated host — so the architecture must keep that choice and any later move cheap. Contributors include AI coding sessions — gates must be automated and objective wherever possible.

Decision

Gitea Actions is the CI/CD system (GitHub-Actions-compatible syntax); an act_runner runs on the VPS (188.245.116.44) with Docker access.
Images are built once per change and promoted, never rebuilt per stage: pushed to the Gitea container registry (gitea.101010.cloud/stwaidele/dorfteich-{web,api,collab}), tagged with the git SHA plus moving tags test, int, and semver tags for releases.
Pipeline (details in deployment.md):
1. PR / push: lint, typecheck, unit tests, build; PRs must be green to merge into main.
2. Merge to main: build + push images (SHA tag) → deploy to Test automatically → run the Playwright e2e suite against Test.
3. Promotion to Int: automatic when e2e on Test is green — Int is the stable preview environment (same images, int tag).
4. Promotion to Prod: manual gate — creating a release tag (vX.Y.Z) triggers the Prod deploy after a required manual approval in the workflow. Database migrations run automatically on container start (ADR 0006); releases with breaking migrations must say so in the release notes.
Deploy mechanism: the runner executes docker compose pull && docker compose up -d in the stage's directory (/home/DOCKER/dorfteich-<stage>/) over SSH (deploy key per stage). Moving Prod to a dedicated host later changes only that SSH target.
Self-hosters consume the same release images via a published docker-compose.yml pinned to semver tags (update strategy in operations.md).

Consequences

One objective quality bar (green e2e on Test) decides Int promotion; the only human gate is the Prod release — matching the risk profile.
The registry, runner, and repo live on the same Gitea — no third-party CI dependency.
e2e stability becomes load-bearing; flaky tests block the pipeline and must be treated as defects (stated in the contributor conventions).

Alternatives considered

GitHub Actions with repo mirror: splits source of truth; rejected.
Manual deploys per stage: does not scale to many small stories and invites drift between stages.

2.8 KiB Raw Blame History