4.9 KiB
Entwicklung und Tests – lokal
Stand: 18.10.2026. Erstellt im Code-Review aus Code und Workflows. Deployment auf dem Raspberry Pi: DEPLOYMENT.md.
Voraussetzungen
- Python 3.12, Node.js (das Build-Image nutzt Node 22; lokal funktioniert auch Node 24)
- PostgreSQL 16. Der Benutzer aus
DB_USERmuss Tabellen anlegen und die Rolletsumugu_runtimeerstellen dürfen (CREATEROLE). Im Compose-Stack ist das der Superuser des Postgres-Containers.
Konfiguration
Das Backend liest ausschließlich die Prozessumgebung. Eine .env-Datei wird nicht automatisch geladen.
| Variable | Pflicht | Default | Bedeutung |
|---|---|---|---|
TSUMUGU_ENV |
ja | – | development oder production; ein anderer Wert verhindert den Start |
DB_NAME, DB_USER, DB_PASSWORD |
ja | – | Owner-Zugang; Migration und Runtime-Rolle |
DB_HOST, DB_PORT |
nein | localhost, 5432 |
– |
DB_RUNTIME_USER |
nein | tsumugu_runtime |
Rolle des laufenden Pools; erhält dasselbe Passwort wie DB_USER |
ALLOWED_ORIGINS |
nein | http://localhost:5173,http://localhost:3094 |
erlaubte Origin-Werte für schreibende Aufrufe |
APP_URL |
nein | http://localhost:5173 |
öffentliche Adresse |
MEDIA_ROOT |
nein | data/media |
Ablage eigener Dateien |
PAPERLESS_MEDIA_ROOT |
nein | leer | lesender Paperless-Ablageordner als Rückfallweg |
SEED_DEMO |
nein | false |
wirkt nur in Development mit Datenbank *_test; in Production verhindert true den Start |
SESSION_TTL_HOURS |
nein | 336 |
Laufzeit einer Session |
UPLOAD_MAX_BYTES |
nein | 20971520 |
Upload-Grenze (Nginx erlaubt 21 MiB) |
Backend starten
cd backend
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
export TSUMUGU_ENV=development DB_NAME=tsumugu_local DB_USER=postgres DB_PASSWORD=…
python -m app.cli migrate
python -m app.cli create-account --email ich@example.test --name "Ich" --password "mindestens-zehn"
uvicorn main:app --reload --port 8000
Das erste per CLI angelegte Konto wird Betreiber. Alternativ zeigt die Anmeldeseite auf einer leeren Datenbank das Formular „Betreiberkonto“ (siehe Review R-04). python -m app.entrypoint entspricht dem Containerstart: Migration, Entfernen von Fixture-Konten, danach Uvicorn auf Port 8000.
Frontend starten
cd frontend
npm ci
npm run dev # http://localhost:5173, Proxy für /api und /health auf 127.0.0.1:8000
Ein anderes Backend erreicht der Proxy über VITE_API_PROXY. Über HTTP heißt das Session-Cookie jinkendo-session. Die Kennzeichnung „Entwicklungsumgebung“ erscheint im Vite-Server automatisch, im Image über VITE_TSUMUGU_ENV=development.
Produktionsbuild: npm run build. Für Development-Images ergänzt mark-environment.mjs danach Titel, Manifest und Farbe.
Tests
Backend
Die Suite läuft gegen echtes PostgreSQL. Sie verweigert jede Datenbank, deren Name nicht auf _test endet, sowie tsumugu, tsumugu_dev, postgres und die Templates. Vor und nach jedem Test werden alle Tabellen geleert.
cd backend
createdb tsumugu_local_test
export DB_NAME=tsumugu_local_test DB_USER=… DB_PASSWORD=… DB_HOST=localhost
python -m pytest tests -ra --basetemp=.pytest-tmp
conftest.pysetztTSUMUGU_ENV=development,ALLOWED_ORIGINS=http://testserver,SEED_DEMO=falseund ein temporäresMEDIA_ROOT.- Unter Windows kann das Standard-Temp-Verzeichnis von pytest gesperrt sein.
--basetemp=.pytest-tmpumgeht das; der Ordner gehört nicht ins Repository. - Zwei Läufe dürfen nicht gleichzeitig dieselbe Testdatenbank verwenden.
- Paperless und IMAP werden in den Tests durch lokale Attrappen ersetzt. Es entsteht kein Netzzugriff.
Frontend
cd frontend
node --test src/list-meta.test.mjs
Weitere Frontend-Tests gibt es nicht. Ein npm test-Skript ist nicht registriert.
In CI
.gitea/workflows/test.yml erzeugt auf der Dev-Postgres die Datenbank tsumugu_test neu und führt die Suite im Backend-Image aus. Danach folgen ein lesender Health-Smoke der laufenden Dev-App und ein Frontend-Build. Bekannte Schwächen: Review 07.
Neue Migration
- Datei
backend/migrations/YYYYMMDDTHHMMSSZ_kurzname.sqlanlegen, Zeitstempel in UTC, lexikalisch nach der letzten. - Keine eigene Transaktionssteuerung in der Datei; der Runner kapselt jede Datei.
- Angewandte Dateien nie ändern: Die Prüfsumme im Ledger verhindert danach den Start.
- DATENMODELL_IST.md nachziehen.
Neue Route
- Route in
api/routes.py,api/sources.pyoderapi/export.pymitDepends(get_principal)undDepends(get_conn)anlegen. - Rechte über die Funktionen in
access/policy.pyprüfen, nie nur im Frontend. - Änderung samt
audit(...)in derselben Verbindung. - API_REFERENZ.md nachziehen.