2026-05-21 10:36:16 +02:00
# Serienbrief – ‑
Web‑ ‑ ‑
Zielumgebung: internes LAN, hinter zentralem Reverse‑ ‑ ‑ ‑
---
## Inhaltsverzeichnis
1. [Funktionsumfang ](#funktionsumfang )
2. [Architekturübersicht ](#architekturübersicht )
3. [Tech‑ ](#techstack )
4. [Komponenten im Detail ](#komponenten-im-detail )
5. [Verzeichnisstruktur ](#verzeichnisstruktur )
6. [Datenfluss eines Serienbrief‑ ](#datenfluss-eines-serienbriefjobs )
2026-05-22 09:14:31 +02:00
7. [Single‑ ‑ ](#singleletterpreview )
8. [Datenmodell ](#datenmodell )
9. [Sicherheitskonzept ](#sicherheitskonzept )
10. [Netzwerk & Ports ](#netzwerk--ports )
11. [Volumes & Persistenz ](#volumes--persistenz )
12. [Konfiguration ](#konfiguration )
13. [Inbetriebnahme ](#inbetriebnahme )
14. [Entwicklung in VS Code ](#entwicklung-in-vs-code )
15. [Tests ](#tests )
16. [Betrieb & Wartung ](#betrieb--wartung )
17. [Datenschutz & Compliance ](#datenschutz--compliance )
18. [Bekannte Einschränkungen & Roadmap ](#bekannte-einschränkungen--roadmap )
2026-05-21 10:36:16 +02:00
---
## Funktionsumfang
- DOCX‑ ‑ `{{ feldname }}` ) via **docxtpl**
- CSV‑ ‑ ‑
2026-05-22 09:14:31 +02:00
- **Single‑ ‑ ‑ ‑ ‑
- Asynchrone Verarbeitung des Komplett‑ ‑
2026-05-21 10:36:16 +02:00
- DOCX → PDF Konversion mit headless **LibreOffice**
- Zusammenführung aller Einzel‑ **pypdf**
- Authentifizierung über Djangos Auth‑ ‑ ‑ **django‑
2026-05-22 09:14:31 +02:00
- Logout per POST‑
2026-05-21 10:36:16 +02:00
- Geschütztes Ausliefern generierter PDFs via **X‑ ‑ (Nginx)
- Audit‑ ‑
- Tägliches Backup (pg_dump + Media‑
2026-05-22 09:14:31 +02:00
- **Test‑ ‑ ‑ ‑ TEST.md ](TEST.md )
2026-05-21 10:36:16 +02:00
---
## Architekturübersicht
```
┌──────────────────────────────────────────────┐
│ Externer LAN‑ ‑
│ https://serienbrief.lan │
└────────────────────┬─────────────────────────┘
│ HTTP (intern)
▼
┌───────────────────────────────────────────────────────────┐
│ Compose‑
│ │
│ ┌───────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ nginx │──▶│ web (Django) │──▶│ db (Postgres 16) │ │
│ │ App‑
│ └─────┬─────┘ └──────┬───────┘ └──────────────────┘ │
│ │ X‑
│ │ static/media ▼ │
│ │ ┌──────────────┐ ┌──────────────────┐ │
│ └────────▶│ redis (Broker)│◀─│ worker (Celery) │ │
│ └──────────────┘ │ LibreOffice+pypdf│ │
│ └──────────────────┘ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ beat (Cron) │ │ backup (pg_dump) │ │
│ └──────────────┘ └──────────────────┘ │
└───────────────────────────────────────────────────────────┘
```
Zwei Bridge‑
- **frontend** – `nginx` ↔ `web` . Einziges Netz mit Port‑
- **backend** – `web` , `worker` , `beat` , `db` , `redis` , `backup` . Kein direktes Internet‑ ‑
---
## Tech‑
| Schicht | Komponente | Version |
|---|---|---|
| Host‑
| Container Runtime | Docker Engine | 27.x+ |
| Orchestrierung | Docker Compose v2 | — |
| App‑
| WSGI (Prod) | Gunicorn | — |
| Task Queue | Celery | 5.4 |
| Broker / Result Backend | Redis | 7‑
| Datenbank | PostgreSQL | 16‑
| DOCX‑
| DOCX→PDF | LibreOffice (headless) | bundled in Image |
| PDF‑
| App‑ ‑
| Auth‑ ‑
| UI‑ ‑
| DB‑
| Python | CPython | 3.12 (slim‑
2026-05-22 09:14:31 +02:00
| Tests | pytest, pytest‑
2026-05-21 10:36:16 +02:00
---
## Komponenten im Detail
### `nginx` – ‑ ‑
- Terminiert **kein** TLS (übernimmt der externe Proxy)
- Liefert Static‑ ‑
- Setzt `X‑ ‑ für Auth‑
- Hört auf `${APP_BIND_IP:-127.0.0.1}:${APP_BIND_PORT:-8080}` (Default Loopback)
- Healthcheck gegen `/healthz`
### `web` –
- Rolle `web` (per `ROLE` ‑
- Stateless, read‑ ‑ `/tmp` als tmpfs
- Settings‑ `base.py` , `dev.py` , `production.py`
- Entrypoint wartet auf DB‑ `migrate` und (in Prod) `collectstatic` aus
- Healthcheck via `/healthz`
2026-05-22 09:14:31 +02:00
- **Synchron**er Preview‑ `/jobs/preview/` ) rendert über LibreOffice direkt im `web` ‑ ‑
2026-05-21 10:36:16 +02:00
### `worker` –
- Verarbeitet `process_mailmerge_job` ‑
- LibreOffice‑ ‑ `/tmp/lo_profile_<task_id>` ) → keine Leaks zwischen Jobs
- `--concurrency=2` , `--max-tasks-per-child=50` (RAM‑ ‑
### `beat` –
- Nutzt `DatabaseScheduler` von django‑ ‑
2026-05-22 09:14:31 +02:00
- Periodic Tasks werden über Django‑
- Aktiv:
- **Retention‑ `mailmerge.cleanup_expired_jobs` ) — täglich 03:15 (`CELERY_TIMEZONE` )
2026-05-21 10:36:16 +02:00
### `db` –
- Eigenes Volume `postgres_data`
- Passwort via Docker‑ `/run/secrets/postgres_password` )
- Init‑ `./postgres/init` (z.B. zusätzliche Extensions)
- `shm_size: 256mb` für komplexere Queries
### `redis` –
- Passwortgeschützt (`REDIS_PASSWORD` aus `.env` )
- AOF persistence + RDB snapshot (`save 900 1` )
- `maxmemory 256mb` mit `allkeys‑
### `backup` –
- Custom‑ `sleep 86400` (kein systemd nötig)
- pg_dump im Custom‑ `-Fc` ) → `pg_restore` ‑
- Media‑ `media_files` ‑ ‑
- Retention 14 Tage (konfigurierbar)
- Schreibt nach `./backups` auf dem Host
---
## Verzeichnisstruktur
```
serienbrief/
├── app/ # Django‑
│ ├── Dockerfile # Multi‑ ‑
│ ├── entrypoint.sh # wait_for_db → migrate → collectstatic → exec CMD
│ ├── manage.py
│ ├── requirements.txt
│ ├── requirements-dev.txt # debugpy, ipython, ruff, pytest, debug-toolbar
│ ├── config/ # Project package
│ │ ├── celery.py
│ │ ├── urls.py
│ │ ├── wsgi.py
│ │ └── settings/
│ │ ├── base.py
│ │ ├── dev.py
│ │ └── production.py
│ ├── mailmerge/ # Hauptapp
│ │ ├── models.py # LetterTemplate, MailMergeJob, JobLogEntry
2026-05-22 09:14:31 +02:00
│ │ ├── views.py # incl. job_preview (synchron)
2026-05-21 10:36:16 +02:00
│ │ ├── admin.py
│ │ ├── forms.py
2026-05-22 09:14:31 +02:00
│ │ ├── urls.py # incl. "jobs/preview/"
2026-05-21 10:36:16 +02:00
│ │ ├── tasks.py # Celery tasks
│ │ ├── services/
│ │ │ ├── docx_renderer.py # docxtpl + LibreOffice
2026-05-22 09:14:31 +02:00
│ │ │ ├── pdf_merge.py # pypdf
│ │ │ └── preview.py # Single-Letter-Preview (synchron)
│ │ ├── tests/ # pytest-django Tests
│ │ │ ├── conftest.py
│ │ │ ├── test_preview_service.py
│ │ │ ├── test_preview_view.py
│ │ │ └── test_preview_integration.py # marker: integration
2026-05-21 10:36:16 +02:00
│ │ └── management/commands/
│ │ └── wait_for_db.py
2026-05-22 09:14:31 +02:00
│ ├── pyproject.toml # pytest config (markers, addopts)
2026-05-21 10:36:16 +02:00
│ └── templates/
2026-05-22 09:14:31 +02:00
│ ├── base.html # Logout via POST-Form (Django 5)
2026-05-21 10:36:16 +02:00
│ ├── registration/login.html
2026-05-22 09:14:31 +02:00
│ └── mailmerge/
│ └── job_form.html # Form + Preview-Button + iframe
2026-05-21 10:36:16 +02:00
├── nginx/
│ ├── nginx.conf
│ └── conf.d/serienbrief.conf
├── postgres/init/ # SQL init scripts
├── secrets/
│ └── postgres_password.txt # 0600, NICHT in Git
├── backups/ # nightly dumps + media tars
├── docker-compose.yml # Produktion
├── docker-compose.override.yml # Dev (automatisch gemerged)
├── .env # NICHT in Git
├── .env.example
├── .devcontainer/ # VS Code Dev Container
├── .vscode/ # launch / tasks / settings / extensions
└── README.md
```
---
## Datenfluss eines Serienbrief‑
1. **Upload Vorlage:** `LetterTemplate` mit DOCX‑
2026-05-22 09:14:31 +02:00
2. **Job‑ User wählt Vorlage + lädt CSV hoch im `job_form.html`
3. **Optional: Preview** — Button »Vorschau (erste Zeile)« löst synchronen POST an `/jobs/preview/` aus, Ergebnis‑
4. **Submit:** Klick auf »Job starten« → `MailMergeJob(status=queued)` angelegt
5. **Enqueue:** View löst `process_mailmerge_job.delay(job.pk)` aus
6. **Worker holt Task:**
2026-05-21 10:36:16 +02:00
- Liest CSV (UTF‑
- Iteriert Zeilen → docxtpl rendert pro Zeile eine temporäre DOCX in `/tmp`
- LibreOffice (`soffice --headless --convert-to pdf …` ) erzeugt pro DOCX ein PDF
- pypdf merged alle PDFs in eine Ausgabedatei unter `media_files`
- `JobLogEntry` s pro Schritt; Status `running → done` bzw. `failed`
2026-05-22 09:14:31 +02:00
7. **UI‑ HTMX fragt `/jobs/<id>/status/` alle ~2 s ab → Fortschrittsbalken
8. **Download:** Nutzer klickt Download → View prüft Auth → Antwort enthält `X‑ ‑ → Nginx streamt das PDF
---
## Single‑ ‑
Vor dem Komplett‑ ‑ ‑
### Design‑
| Aspekt | Wahl | Begründung |
|---|---|---|
| Ausführung | **synchron im `web`‑ | Renderzeit < 5 s, kein Celery‑
| Persistenz | **keine** — kein `MailMergeJob` , keine Datei auf `media_files` | Preview ist ephemer, hinterlässt keine DSGVO‑
| Render‑ `/tmp` (size‑ ‑ ‑ ‑ ‑ ‑
| Validierung | strikt: fehlende Spalten → `PreviewError` | Im Komplett‑ ‑ ‑
| Auth | `@login_required` , POST‑ ‑
| Response | `Content‑ , `Content‑ | iframe im Form zeigt das PDF direkt |
### Response‑
Die Preview‑ ‑ ‑
- `X-Preview-Placeholders` — Komma‑
- `X-Preview-Extra-Columns` — Komma‑ ‑
### Fehlerfälle
| Auslöser | Verhalten |
|---|---|
| Form ungültig (fehlende Datei, falsche Extension) | Formular wird mit Django‑ ‑
| `PreviewError` (z.B. Spalte fehlt) | Formular mit `preview_error` ‑
| LibreOffice‑ ‑
2026-05-21 10:36:16 +02:00
---
## Datenmodell
```text
LetterTemplate
├── id, name (unique), description
├── docx_file (FileField → media/templates/)
├── created_by (FK User), created_at, updated_at
└── is_active
MailMergeJob
├── id, template (FK LetterTemplate)
├── csv_file (FileField → media/jobs/<id>/input.csv)
├── output_pdf (FileField → media/jobs/<id>/output.pdf)
├── status: queued | running | done | failed
├── total_rows, processed_rows
├── created_by, created_at, started_at, finished_at
└── error_message
JobLogEntry
├── id, job (FK MailMergeJob, related_name="log_entries")
├── level: info | warning | error
├── message, created_at
```
---
## Sicherheitskonzept
Im Sinne der Space‑ ‑ ‑
### Container‑
- `no-new-privileges: true` bei allen Services
- `read_only: true` für `web` , `worker` , `beat` (writable nur via tmpfs `/tmp` )
- Non‑ ‑ `app` (UID/GID 1000, anpassbar per Build‑
- Minimales Image (`python:3.12-slim-bookworm` ), Multi‑ ‑ ‑ ‑
- Ressourcen‑
- `tmpfs` ‑ `size=256M` , etc.)
### Netzwerk
- Zwei isolierte Bridges (`frontend` , `backend` )
- Nur `nginx` bindet nach außen, default auf **Loopback**
- DB und Redis ausschließlich auf `backend`
- Externer Proxy übernimmt TLS, HSTS, ggf. IP‑
### Secrets
- Postgres‑ ‑ `./secrets/postgres_password.txt` , Mode 0600)
- Redis‑ ‑ ‑ `.env` (nicht in Git)
- `.env` und `secrets/` sind in `.gitignore` ausgenommen
### Anwendungs‑
- django‑
- CSRF aktiv, Trusted Origins explizit gepflegt
- `SECURE_PROXY_SSL_HEADER` gesetzt, damit Django HTTPS hinter dem externen Proxy korrekt erkennt
- `USE_X_FORWARDED_HOST=True`
- X‑ ‑ ‑
- Session‑ `HttpOnly` , `SameSite=Lax` , `Secure` (in Prod)
### Defense‑ ‑
- AppArmor‑ `--security-opt apparmor=...` ) –
- seccomp‑
- Image‑ `trivy` , `grype` ) in CI integrieren
- Renovate/Dependabot für Base‑ ‑
---
## Netzwerk & Ports
| Port (Host) | Service | Sichtbarkeit | Zweck |
|---|---|---|---|
| 8080 | nginx | `${APP_BIND_IP}` | HTTP für externen Proxy |
| 8000 | web | nur Dev | Django runserver |
| 5678 | web (Dev) | nur Dev | debugpy |
| 5432 | db | nur Dev | Postgres (Tools wie pgAdmin) |
| 6379 | redis | nur Dev | Redis‑
In Produktion bleiben **nur** Port 8080 (intern an externen Proxy) erreichbar.
---
## Volumes & Persistenz
| Volume | Inhalt | Backup? |
|---|---|---|
| `postgres_data` | Postgres‑
| `redis_data` | AOF + RDB | nein (Broker‑
| `static_files` | Generierte Static‑ `collectstatic` ) |
| `media_files` | Hochgeladene Templates, CSVs, generierte PDFs | tar nightly |
| `nginx_cache` | Nginx Cache | nein |
| `nginx_run` | Nginx PID/Socket | nein |
Bind‑ `./app:/app` für Live‑
---
## Konfiguration
`.env` (aus `.env.example` abgeleitet) — Auszug:
```env
# App
APP_VERSION = 1.0.0
APP_BIND_IP = 127.0.0.1
APP_BIND_PORT = 8080
APP_UID = 1000
APP_GID = 1000
# Django
DJANGO_SECRET_KEY = <openssl rand -base64 64>
DJANGO_DEBUG = False
DJANGO_ALLOWED_HOSTS = serienbrief.lan,127.0.0.1,localhost
CSRF_TRUSTED_ORIGINS = https://serienbrief.lan
SECURE_PROXY_SSL_HEADER = HTTP_X_FORWARDED_PROTO,https
USE_X_FORWARDED_HOST = True
# Postgres
POSTGRES_DB = serienbrief
POSTGRES_USER = serienbrief
DATABASE_URL = postgres://serienbrief:<HEX-PWD>@db:5432/serienbrief
# Redis
REDIS_PASSWORD = <openssl rand -hex 32>
CELERY_BROKER_URL = redis://:<REDIS_PASSWORD>@redis:6379/0
CELERY_RESULT_BACKEND = redis://:<REDIS_PASSWORD>@redis:6379/1
# Business
JOB_RETENTION_DAYS = 30
```
**Wichtig:**
- `secrets/postgres_password.txt` muss exakt denselben Wert enthalten wie in `DATABASE_URL`
- Datei darf **kein** abschließendes Newline enthalten — Generierung: `openssl rand -hex 32 | tr -d '\n' > secrets/postgres_password.txt && chmod 600 secrets/postgres_password.txt`
- Hex statt Base64, weil Base64‑ `=` URL‑ `DATABASE_URL` bricht
---
## Inbetriebnahme
### Voraussetzungen
- Ubuntu 22.04/24.04 LTS, aktueller Patch‑
- Docker Engine 27.x+ und Compose v2 (apt‑ `docker-ce` + `docker-compose-plugin` , nicht Snap)
- Host‑ `docker` ‑ `sudo usermod -aG docker $USER` , dann Re‑
### Erststart
```bash
# 1. Repo holen / entpacken in z.B. ~/projekte/serienbrief
cd ~/projekte/serienbrief
# 2. Konfiguration aus Template ableiten
cp .env.example .env
$EDITOR .env # Werte ausfüllen, siehe oben
# 3. Postgres‑
openssl rand -hex 32 | tr -d '\n' > secrets/postgres_password.txt
chmod 600 secrets/postgres_password.txt
# → diesen Wert auch in DATABASE_URL eintragen
# 4. Image bauen
docker compose build
# 5. Hochfahren
docker compose up -d
# 6. Status & Logs
docker compose ps -a
docker compose logs -f web
# 7. Superuser anlegen
docker compose exec web python manage.py createsuperuser
```
2026-05-21 17:54:38 +02:00
### Externen Reverse-Proxy konfigurieren
Der Stack liefert intern HTTP auf `${APP_BIND_IP}:${APP_BIND_PORT}` aus (Default `127.0.0.1:8080` ). Der externe Proxy übernimmt TLS-Terminierung und die nach außen sichtbare Domain.
#### Voraussetzungen für externen Zugriff
Wenn der Proxy auf einem **anderen Host** läuft (typisch bei Nginx Proxy Manager als eigener Container/VM), muss `APP_BIND_IP` von `127.0.0.1` auf eine LAN-erreichbare Adresse umgestellt werden:
```bash
# LAN-IP des Docker-Hosts ermitteln
ip -4 -br a | grep -v lo
# In .env eintragen (Beispiel)
sed -i 's/^APP_BIND_IP=.*/APP_BIND_IP=192.168.10.42/' .env
docker compose up -d
```
Alternativ `0.0.0.0` für alle Interfaces — die explizite IP ist sicherheitstechnisch sauberer.
Firewall absichern, damit nur der Proxy-Host auf 8080 zugreifen darf:
```bash
sudo ufw allow from <proxy-host-ip> to any port 8080 proto tcp comment 'reverse proxy'
sudo ufw deny 8080
```
#### Django-Seite anpassen
Die externe Domain muss in `.env` eingetragen sein, sonst lehnt Django die Requests ab (400 Bad Request bzw. 403 CSRF):
```env
DJANGO_ALLOWED_HOSTS = serienbrief.example.lan,localhost,127.0.0.1
CSRF_TRUSTED_ORIGINS = https://serienbrief.example.lan,http://localhost:8080,http://127.0.0.1:8080
```
Nach Änderung `docker compose restart web` .
#### Variante A: Nginx Proxy Manager (NPM)
Im NPM-Webinterface unter **Proxy Hosts → Add Proxy Host** :
| Feld | Wert |
|---|---|
| Domain Names | `serienbrief.example.lan` |
| Scheme | `http` |
| Forward Hostname / IP | LAN-IP des Docker-Hosts (z.B. `192.168.10.42` ) |
| Forward Port | `8080` |
| Cache Assets | aus |
| Block Common Exploits | an |
| Websockets Support | an (HTMX nutzt nur AJAX, schadet aber nicht) |
Im Tab **Custom Locations** oder **Advanced** zusätzlich:
```nginx
client_max_body_size 50M ;
proxy_set_header X-Forwarded-Proto $scheme ;
proxy_set_header X-Forwarded-Host $host ;
proxy_set_header X-Real-IP $remote_addr ;
proxy_read_timeout 300s ;
proxy_send_timeout 300s ;
```
NPM setzt `Host` , `X-Forwarded-For` und Standard-Header bereits selbst. **Pflicht** ist nur `X-Forwarded-Proto $scheme` , weil Djangos `SECURE_PROXY_SSL_HEADER` darauf basiert.
TLS-Zertifikat (Let's Encrypt für interne Domains via DNS-Challenge, oder eigenes CA-Cert) im Tab **SSL** zuweisen.
#### Variante B: Generisches Nginx / OpenResty
2026-05-21 10:36:16 +02:00
```nginx
server {
listen 443 ssl http2 ;
2026-05-21 17:54:38 +02:00
server_name serienbrief.example.lan ;
2026-05-21 10:36:16 +02:00
ssl_certificate /etc/ssl/lan/serienbrief.crt ;
ssl_certificate_key /etc/ssl/lan/serienbrief.key ;
2026-05-21 17:54:38 +02:00
client_max_body_size 50M ; # für CSV/DOCX-Uploads
2026-05-21 10:36:16 +02:00
location / {
proxy_pass http://<docker-host-ip>:8080 ;
2026-05-21 17:54:38 +02:00
proxy_http_version 1 .1 ;
2026-05-21 10:36:16 +02:00
proxy_set_header Host $host ;
proxy_set_header X-Real-IP $remote_addr ;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for ;
proxy_set_header X-Forwarded-Proto https ;
2026-05-21 17:54:38 +02:00
proxy_set_header X-Forwarded-Host $host ;
proxy_read_timeout 300s ;
proxy_send_timeout 300s ;
2026-05-21 10:36:16 +02:00
proxy_redirect off ;
}
}
```
2026-05-21 17:54:38 +02:00
#### Diagnose bei 502 Bad Gateway
Vom Proxy-Host aus testen:
```bash
# TCP-Connect — "succeeded" erwartet
nc -zv <docker-host-ip> 8080
# HTTP-Request — 200/302 erwartet
curl -v -H "Host: serienbrief.example.lan" http://<docker-host-ip>:8080/
```
Typische Ursachen:
- `Connection refused` → `APP_BIND_IP` steht noch auf `127.0.0.1`
- `Timeout` → Firewall blockt
- 502 ohne Connect-Fehler → falsche Upstream-IP im Proxy-Eintrag
2026-05-21 10:36:16 +02:00
---
## Entwicklung in VS Code
- `.devcontainer/devcontainer.json` referenziert den Compose‑ ‑
- `.vscode/launch.json` enthält Configs:
- **Django: runserver (attach)** → debugpy auf 5678
- **Django: pytest** → führt Tests im Container aus
- `.vscode/tasks.json` für `makemigrations` , `migrate` , `shell` , `collectstatic`
- `.vscode/extensions.json` empfiehlt: Python, Pylance, Django, Docker, Even Better TOML, Ruff
### Workflow
```bash
# Stack hochfahren (Override greift automatisch)
docker compose up -d
# Code‑Änderungen werden via Bind‑
# runserver reloaded automatisch
# Debugging: F5 in VS Code → attach an debugpy:5678
```
2026-05-22 09:14:31 +02:00
**Hinweis zum Compose‑ Niemals `docker compose -f docker-compose.yml up -d` verwenden — das ignoriert die Override‑ ‑ ‑ `docker-compose.yml` + `docker-compose.override.yml` automatisch, wenn keine `-f` ‑
2026-05-21 10:36:16 +02:00
### Wichtige Unterschiede Dev ↔ Prod
| Aspekt | Dev | Prod |
|---|---|---|
| WSGI | `runserver` | Gunicorn |
| Code | Bind‑ `./app:/app` | im Image |
| Healthcheck | deaktiviert | aktiv (`/healthz` ) |
| `read_only` | aus | an |
| `DJANGO_DEBUG` | True | False |
| `collectstatic` | auto im Entrypoint | im Entrypoint |
| `target` | `dev` (mit debugpy, ipython, pytest) | `runtime` |
---
2026-05-22 09:14:31 +02:00
## Tests
Die Test‑ `app/mailmerge/tests/` und ist in drei Schichten organisiert:
| Layer | Datei | Was wird geprüft | LibreOffice |
|---|---|---|---|
| Service‑ `test_preview_service.py` | CSV‑ ‑ ‑
| View | `test_preview_view.py` | HTTP‑ ‑ ‑ ‑ ‑
| Integration | `test_preview_integration.py` | End‑ ‑ `soffice --headless` | **real** (Marker `integration` ) |
**Pytest‑ (`app/pyproject.toml` ):
- `--reuse-db` für schnelle Re‑
- Default‑ `-m 'not integration'` — Integration‑
- `python_files = ["test_*.py", "*_test.py", "tests.py"]`
**Schnellstart:**
```bash
# Erster Lauf (DB anlegen)
docker compose exec web pytest mailmerge/tests/ -v --create-db
# Normale Re‑
docker compose exec web pytest mailmerge/tests/ -v
# Inkl. Integration (langsamer, benötigt LibreOffice im Image)
docker compose exec web pytest mailmerge/tests/ -m integration -v
```
Detaillierte Anleitung inkl. Coverage, Fixtures, Debugging und CI‑ ** [TEST.md ](TEST.md )**.
---
2026-05-21 10:36:16 +02:00
## Betrieb & Wartung
### Häufige Operationen
```bash
# Logs eines einzelnen Services
docker compose logs -f worker
# In den Container schauen
docker compose exec web bash
docker compose exec db psql -U serienbrief
# Migration nach Modelländerung
docker compose exec web python manage.py makemigrations
docker compose exec web python manage.py migrate
# Statics neu generieren
docker compose exec web python manage.py collectstatic --noinput
# Celery‑
docker compose exec worker celery -A config inspect active
docker compose exec worker celery -A config inspect reserved
```
### Updates
```bash
# Code aktualisieren
git pull
# Image neu bauen
docker compose build --pull
# Mit Zero‑ ‑
docker compose up -d
# DB‑
docker compose exec web python manage.py migrate
```
### Backup & Restore
```bash
# Manuelles Backup erzwingen
docker compose restart backup
docker compose logs --tail= 50 backup
# Restore (Beispiel)
docker compose exec -T db pg_restore -U serienbrief -d serienbrief --clean < backups/db_20260521_030000.dump
```
### Monitoring (Empfehlung, nicht enthalten)
- `docker stats` für ad‑ ‑
- Healthcheck‑ `docker compose ps`
- Container‑ `json-file` rotiert 5×
- Optional: Prometheus + cAdvisor + node_exporter, Loki für Logs
---
## Datenschutz & Compliance
- **Rechtsgrundlage:** Verarbeitung personenbezogener Adress‑
- **Speicherort:** Innerbetrieblicher Server, kein Cloud‑
- **Zugriffssteuerung:** Nur authentifizierte User; Trennung Templates/Jobs aktuell flach — Mandanten‑
2026-05-22 09:14:31 +02:00
- **Aufbewahrung:** Jobs + CSVs + Output‑ `JOB_RETENTION_DAYS` (default 30) automatisch gelöscht. Der Retention‑ ‑ ‑ ‑ ‑ `docker compose exec web python manage.py cleanup_jobs --dry-run`
2026-05-21 10:36:16 +02:00
- **Audit:** Jeder Job hat ein `JobLogEntry` ‑
- **Backup‑ ‑ `./backups` liegt aktuell unverschlüsselt — für produktiven Einsatz LUKS/Filesystem‑ **dringend empfohlen**
- **DSFA‑ ‑
---
## Bekannte Einschränkungen & Roadmap
### Tech‑
- Postgres‑ `DATABASE_URL` + Secret‑ `DATABASE_URL` aus `*_FILE` ‑
- Keine LDAP/AD‑ ‑
2026-05-22 09:14:31 +02:00
- CSV‑ ‑ **Haupt‑ ‑ warn‑ ‑
2026-05-21 10:36:16 +02:00
- Image enthält LibreOffice (~400 MB) — könnte in separates Worker‑
2026-05-22 09:14:31 +02:00
- Tests decken Preview + Retention ab — Haupt‑ ‑ ‑ `run_mailmerge` , Status‑ ‑ ‑
### Erledigt
- [x] Single‑ ‑ ‑ ‑
- [x] Test‑ ‑
- [x] Logout via POST‑
- [x] Retention‑ `mailmerge.cleanup_expired_jobs` , täglich)
2026-05-21 10:36:16 +02:00
### Roadmap (kurzfristig)
2026-05-22 09:14:31 +02:00
- [ ] CSV‑ ‑
- [ ] Tests für Celery‑ `run_mailmerge` (mit `CELERY_TASK_ALWAYS_EAGER` )
2026-05-21 10:36:16 +02:00
- [ ] Mandanten‑
2026-05-22 09:14:31 +02:00
- [ ] LDAP‑ `django‑ ‑
- [ ] Postgres‑ `*_FILE` ‑
2026-05-21 10:36:16 +02:00
### Roadmap (mittelfristig)
- [ ] AppArmor‑
- [ ] Image‑
- [ ] Separate Worker‑ ‑
- [ ] AES‑
- [ ] Optional: Konvertierung über Gotenberg statt LibreOffice‑ ‑
---
## Lizenz & Verantwortlichkeit
Internes Projekt. Verantwortlich für Konzept & Betrieb: **Datenschutzkoordination / IT‑ .
Keine externe Lizenz festgelegt — Verteilung ausschließlich innerbetrieblich.
