Files
tsumugu/docs/DEPLOYMENT.md
StommerandClaude Sonnet 5.5 363ecdfd0a
Deploy Development / deploy (push) Successful in 51s
Test Suite / pytest-backend (push) Successful in 6m22s
Test Suite / frontend-build (push) Successful in 25s
Test Suite / smoke-dev (push) Successful in 0s
Starte test.yml wieder mit dem Push und warte auf den Checkout des Dev-Deploys, weil workflow_run hier nicht auslöst.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 10:24:11 +01:00

96 lines
7.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Deployment – Tsumugu
**Stand:** 2026-10-17
**Server:** Raspberry Pi (`192.168.2.49`) — gleicher Host wie Mitai, Shinkan, Kairo und Kanshō, **eigenes** Compose-Projekt
**Runner:** Gitea Actions (`/home/lars/gitea-runner/`), Label `ubuntu-latest`
**Repo:** `http://192.168.2.144:3000/Lars/tsumugu.git`
Der Mechanismus ist von Kanshō übernommen: der Runner auf dem Pi checkt den Branch in ein festes Verzeichnis aus, baut die Images und startet Compose. Watchtower bleibt aus.
Unter `/home/lars/docker/` legt der Lauf nur diese zwei Verzeichnisse an:
| | Production | Development |
|---|------------|-------------|
| **Git-Branch** | `main` | `develop` |
| **Server-Verzeichnis** | `/home/lars/docker/tsumugu` | `/home/lars/docker/tsumugu-dev` |
| **Frontend-Port** | 3007 | 3094 |
| **Backend-Port** | 8007 | 8094 |
| **PostgreSQL** | nur Compose-Netz, DB `tsumugu` | nur Compose-Netz, DB `tsumugu_dev` |
| **Domain** | tsumugu.jinkendo.de | dev.tsumugu.jinkendo.de |
| **Öffentliche URL** | https://tsumugu.jinkendo.de | https://dev.tsumugu.jinkendo.de |
| **Compose** | `docker-compose.yml` | `docker-compose.dev-env.yml` |
3005 ist auf dem Pi durch Bookstack belegt, 3006/8005 und 3096/8096 durch Kanshō. 3002–3004 und 3097–3099 gehören Mitai, Shinkan und Kairo. BuyingAgent hält 8006 und 8095. Tsumugu nimmt deshalb 3007/8007 und 3094/8094.
---
## Gitea Actions
| Workflow | Trigger | Zweck |
|----------|---------|--------|
| `deploy-dev.yml` | Push `develop` | Deploy nach `/home/lars/docker/tsumugu-dev`, Health `localhost:8094` und `localhost:3094` |
| `deploy-prod.yml` | Push `main` | Deploy nach `/home/lars/docker/tsumugu`, Health `localhost:8007` und `localhost:3007` |
| `test.yml` | Push auf `develop` (wartet, bis der Dev-Checkout den Commit enthält), manuell | Pytest gegen `tsumugu_test` auf der Dev-Postgres, Smoke der laufenden Dev-App, Frontend-Build |
Gearbeitet wird auf `develop`. Production entsteht nur durch einen Merge-Commit `develop` → `main` (`git merge --no-ff develop` auf `main`) und den anschließenden Push von `main`. Kein Fast-Forward, kein direkter Commit auf `main`, kein manuelles `git pull` auf dem Prod-Checkout. Gitea (`deploy-prod.yml`) ist der einzige Prod-Schreibpfad für Code.
Fehlt beim ersten Lauf die Host-`.env`, legt der Workflow sie an. Development bekommt die dokumentierten Dev-Defaults. Production bekommt ein zufälliges `DB_PASSWORD`, das nur in `/home/lars/docker/tsumugu/.env` steht und nicht ins Log geschrieben wird. Spätere Läufe überschreiben eine vorhandene `.env` nicht. `git reset --hard` lässt die Datei liegen, weil sie nicht im Repo ist.
Der Backend-Container migriert beim Start, entfernt Konten mit Herkunft `fixture` und bedient danach den API-Prozess. Der Host-Port des Backends bleibt an `127.0.0.1` gebunden; von außen ist nur das Frontend erreichbar, das `/api/` im Compose-Netz weiterreicht. Eigene Dateien liegen im Volume `dev-tsumugu-media` bzw. `tsumugu-media`. Der Paperless-Ablageordner `/media/lars/paperless/media` wird nur lesend nach `/paperless-media` gereicht. Tsumugu öffnet daraus eine Datei erst, wenn die Paperless-API für genau dieses Dokument einen relativen Pfad nennt und die Vorschau über HTTP keine anzeigbare Datei liefert.
Die Pflicht-Suite ist der eigene Workflow `test.yml`, nach dem Vorbild von Kanshō gegen die bestehende Dev-Postgres, in der Datenbank `tsumugu_test` neben `tsumugu_dev`. Der Lauf beendet Verbindungen auf `tsumugu_test`, verwirft diese Datenbank und legt sie neu an. `tsumugu_dev` und `tsumugu` werden nicht beschrieben. Pytest startet im schon gebauten Backend-Image, mit dem Checkout nur lesend eingehängt. Zusätzlich prüft der Workflow die Health-URLs der laufenden Dev-App und baut das Frontend. `SEED_DEMO` bleibt in beiden Compose-Dateien aus. Steht es in Produktion trotzdem auf wahr, startet das Backend nicht. Beispieldaten entstehen nur, wenn die Suite das in `tsumugu_test` ausdrücklich tut. Das erste Konto auf einer leeren Umgebung wird über die Anmeldeseite zum Betreiber und legt weitere Nutzer an.
---
## Bekannte Betriebsgrenzen (Stand Code-Review 18.10.2026)
Diese Punkte sind im [Code-Review](review/06_BEFUNDE.md) beschrieben. Sie stehen hier, damit sie beim Betrieb sichtbar bleiben.
| Thema | Ist-Stand | Folge für den Betrieb | Review |
|---|---|---|---|
| Betreiberkonto | Auf einer leeren Datenbank legt die öffentliche Anmeldeseite das Betreiberkonto an. Keine MFA | Nach jedem Neuaufsetzen einer Umgebung sofort selbst anmelden, bevor die Adresse öffentlich erreichbar ist. Alternativ vorher `docker compose exec backend python -m app.cli create-account --email … --name … --password …` ausführen | R-04 |
| Sicherung | Es gibt kein Backup von Datenbank und Volume `tsumugu-media`/`dev-tsumugu-media` und keinen geprobten Restore | Laut technischer Spezifikation 8.2 nur synthetische Daten in Produktion, bis Paket P7 umgesetzt ist | R-21 |
| Release | `deploy-prod.yml` baut bei jedem Push auf `main` neu. Tests laufen nur auf `develop`, sobald der Dev-Deploy den Commit ausgecheckt hat | Vor dem Merge nach `main` den grünen `test.yml`-Lauf zum selben Stand prüfen | R-21, R-27 |
| Datenbankzugang | Das Backend migriert beim Start mit dem Owner-Zugang. Die Runtime-Rolle `tsumugu_runtime` erhält dasselbe Passwort wie `DB_USER` | Ein Wechsel von `DB_PASSWORD` ändert beim nächsten Start beide Rollen | R-09 |
| Quellen-Geheimnisse | Paperless-Token und IMAP-Passwörter stehen unverschlüsselt in der Tabelle `connectors` | Datenbank-Dumps wie Zugangsdaten schützen | R-05 |
| Sessions | 14 Tage gültig, keine Leerlaufabmeldung, kein Passwortwechsel in der Anwendung | Passwort nur über die Datenbank oder ein neues Konto änderbar | R-08 |
| Testläufe | `test.yml` startet je Push einmal, parallel zum Deploy, und wartet auf dessen Checkout (`workflow_run` startete auf dieser Gitea nicht verlässlich); alle Läufe teilen die Datenbank `tsumugu_test`, und das Image bleibt das Laufzeitimage | Zwei manuelle Läufe gleichzeitig vermeiden; sie würden sich die Datenbank wegnehmen | R-27 |
---
## Erreichbarkeit von außen
TLS endet wie bei Kanshō auf dem Synology-NAS `192.168.2.63` (DSM Reverse Proxy), nicht auf dem Pi.
| Domain | Ziel |
|--------|------|
| `dev.tsumugu.jinkendo.de` | `http://192.168.2.49:3094` |
| `tsumugu.jinkendo.de` | `http://192.168.2.49:3007` |
DNS bzw. AdGuard-Rewrite für beide Namen auf `192.168.2.63`. Im DSM-Reverse-Proxy Lese- und Sende-Timeout auf 600s setzen. Bis die Regeln stehen, bleibt der LAN-Zugriff über die Publish-Ports:
- Development: `http://192.168.2.49:3094`
- Production: `http://192.168.2.49:3007`
`nginx/tsumugu.conf` und `nginx/tsumugu-dev.conf` sind die Host-nginx-Variante, falls TLS später auf dem Pi endet. Sie sind nicht der aktuelle Pfad.
---
## Manuelles Deploy
```bash
# Development
cd /home/lars/docker/tsumugu-dev
git fetch origin develop && git reset --hard origin/develop
docker compose -f docker-compose.dev-env.yml build --no-cache backend frontend
docker compose -f docker-compose.dev-env.yml up -d --wait
curl -sf http://localhost:8094/api/health
# Production
cd /home/lars/docker/tsumugu
git fetch origin main && git reset --hard origin/main
docker compose build --no-cache backend frontend
docker compose up -d --wait
curl -sf http://localhost:8007/api/health
```