7.0 KiB
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 develop, nach erfolgreichem Dev-Deploy, 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 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 zweimal auf derselben Datenbank tsumugu_test |
Ein roter Lauf kann vom parallelen Lauf verursacht sein; Ergebnis des Einzellaufs prüfen | 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
# 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