Deploy Development / deploy (push) Successful in 52s
Der Hinweis zu Tags und Zusatzfeld sitzt wieder in paperless_documents, damit die Signatur von _paperless_get bleibt. Der Push-Trigger entfällt, weil er einen zweiten Lauf auf derselben Testdatenbank startete. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
96 lines
7.1 KiB
Markdown
96 lines
7.1 KiB
Markdown
# 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` | Nach erfolgreichem Dev-Deploy (`workflow_run`), 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` nach dem Dev-Deploy | 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, nach dem Dev-Deploy; 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
|
||
```
|