# Entwicklung und Tests – lokal **Stand:** 18.10.2026. Erstellt im Code-Review aus Code und Workflows. Deployment auf dem Raspberry Pi: [DEPLOYMENT.md](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_USER` muss Tabellen anlegen und die Rolle `tsumugu_runtime` erstellen 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 ```bash 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 ```bash 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. ```bash 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.py` setzt `TSUMUGU_ENV=development`, `ALLOWED_ORIGINS=http://testserver`, `SEED_DEMO=false` und ein temporäres `MEDIA_ROOT`. - Unter Windows kann das Standard-Temp-Verzeichnis von pytest gesperrt sein. `--basetemp=.pytest-tmp` umgeht 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 ```bash 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](review/07_TESTS_UND_CI.md). ## Neue Migration 1. Datei `backend/migrations/YYYYMMDDTHHMMSSZ_kurzname.sql` anlegen, Zeitstempel in UTC, lexikalisch nach der letzten. 2. Keine eigene Transaktionssteuerung in der Datei; der Runner kapselt jede Datei. 3. Angewandte Dateien nie ändern: Die Prüfsumme im Ledger verhindert danach den Start. 4. [DATENMODELL_IST.md](architecture/DATENMODELL_IST.md) nachziehen. ## Neue Route 1. Route in `api/routes.py`, `api/sources.py` oder `api/export.py` mit `Depends(get_principal)` und `Depends(get_conn)` anlegen. 2. Rechte über die Funktionen in `access/policy.py` prüfen, nie nur im Frontend. 3. Änderung samt `audit(...)` in derselben Verbindung. 4. [API_REFERENZ.md](architecture/API_REFERENZ.md) nachziehen.