Files
tsumugu/docs/DEPLOYMENT.md
T
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

7.0 KiB
Raw Blame History

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