Paperless NGX – Schema & Betrieb

Metadaten

• Version: 1.1
• Datum: 2026-05-20
• Vorgänger: v1.0 (Schema-Doku Paperless-intern)
• System: Paperless NGX auf Mimir (Synology NAS)

Änderungen gegenüber v1.0

• Authentifizierung jetzt zentral über Synology SSO Server (statt lokaler Paperless-User)
• Hostnamen auf Subdomain-Routing umgestellt (paperless.mimir.dyn.veedel.net statt Port-URL)
• Family-User-Setup mit Owner-Zuweisung via Workflows (multi-User-tauglich)
• Wildcard-Cert via Let’s Encrypt mit DNS-Challenge
• Betriebsabschnitt (Backups, Wartung, Troubleshooting) ergänzt

---

1 Komponentenübersicht – wer macht was?

Alle Komponenten laufen auf dem NAS „Mimir”. Keine externen Abhängigkeiten für Login oder Datenzugriff.

Komponente	Rolle	Stack
DSM (Synology)	OS-Plattform, User-Datenbank, SMB-Server	Synology DSM 7
Synology SSO Server	OIDC-Provider, nutzt DSM-User direkt	DSM-Package
Synology Reverse Proxy	TLS-Terminierung, Subdomain-Routing auf Port 443	DSM-eigen
Paperless NGX	Klassifikation, OCR, Suche, Web-UI	Docker
PostgreSQL 17	Datenhaltung Paperless	Docker
Redis	Task-Queue Paperless	Docker
Tika + Gotenberg	Office-Datei-Konvertierung	Docker
acme.sh	Let’s-Encrypt-Zertifikate via DNS-Challenge	Native auf DSM

2 Datenfluss – vom Upload bis zur Ablage

Ein Dokument durchläuft folgende Schritte, vom Augenblick des Uploads bis es im Archiv liegt:

1. Family-User legt Datei in SMB-Share \\mimir\Paperless-Inbox\<user>\ ab
2. Paperless-Consume-Watcher (inotify, 5 s Delay) erkennt die neue Datei
3. OCR und Auto-Klassifikation: Correspondent, Document Type, Tags aus Subdir-Name
4. Workflow „Owner: ” greift: setzt Owner auf gleichnamigen Paperless-User
5. Storage-Path-Logik verschiebt die Datei in den passenden Lebensbereich-Pfad
6. Dokument ist im Web-UI sichtbar – nur für den Owner (und Superuser)

Die Subdir-als-Tag-Logik setzt zusätzlich einen Tag mit dem Namen des Subordners (z.B. philipp). Das ist gewollte Doppelinformation – sie macht es einfach, alle Uploads eines bestimmten Users auch unabhängig vom Owner-Filter zu finden.

3 Authentifizierung

Eine einzige User-Datenbank: DSM-User. Die Authentifizierung läuft an zwei Stellen mit derselben Credentials:

Zugriffspunkt	Auth-Weg	User-Quelle
SMB / Datei-Upload	DSM-nativ (SMB-Protokoll)	DSM-lokale User
Paperless Web-UI	OIDC über Synology SSO Server	DSM-lokale User (via SSO)
DSM-Web	DSM-nativ	DSM-lokale User

Konsequenz: Passwort-Wechsel erfolgt einmal in DSM (Systemsteuerung → Benutzer & Gruppen → Benutzer bearbeiten) und gilt sofort für SMB und Paperless.

3.1 Anforderungen pro Family-User

• DSM-User existiert + Mitglied der Gruppe paperless-users
• Subfolder Paperless-Inbox/<username>/ ist angelegt mit Read/Write-ACL für den User
• Paperless-Workflow „Owner: ” existiert mit Pfad-Filter */<user>/*
• Beim ersten SSO-Login wird ein gleichnamiger Paperless-User automatisch erzeugt (oder einmalig manuell mit lokalem Account verknüpft, falls bereits vorhanden)

3.2 Notfall-Zugang (Break-Glass)

Falls Synology SSO Server kaputt ist (Upgrade-Panne, Service-Crash) und der reguläre Login nicht funktioniert: ein lokaler Paperless-Superuser mit Random-Passwort liegt im Passwort-Manager.

Break-Glass-Voraussetzungen

• PAPERLESS_DISABLE_REGULAR_LOGIN ist nicht gesetzt (oder false) – dann steht der lokale Login als Fallback parallel zur Verfügung
• Login über die Login-Seite mit dem Superuser-Namen + Random-Passwort

Aktueller Status: PAPERLESS_DISABLE_REGULAR_LOGIN ist deaktiviert, lokaler Login als Fallback verfügbar. Falls später auf true gestellt: vorher Break-Glass-Workflow testen.

---

4 Klassifikations-Schema (Kurzfassung)

Detaillierte Beschreibung in v1.0 dieser Doku. Hier nur die Eckpunkte zur Orientierung.

4.1 Document Types

19 funktionale Typen, bei Klassifikation wird genau einer gewählt; in Grenzfällen leer:

Rechnung, Quittung, Mahnung, Kontoauszug, Vertrag, Kündigung, Versicherungspolice, Versicherungsbescheinigung, Schadensmeldung, Lohnabrechnung, Steuerbescheid, Steuererklärung, Behördenbescheid, Antrag, Zertifikat, Zeugnis, Anleitung, Garantie, Vollmacht, Korrespondenz

4.2 Tag-Taxonomie

Fünf funktionale Kategorien, kombinierbar:

Kategorie	Inhalt / Konvention
Lebensbereich (Pflicht, 1×)	arbeit, finanzen, gesundheit, hobby, kind, mobilität, recht, weiterbildung, wohnung
Person (additiv)	robin, vincent, philipp, …
Projekt-/Fall-Tag (flach)	fall-YYYY-kurzname, bewerbung-YYYY-firma, wohnung-YYYY-stadt
Status (optional)	steuer-YYYY, werbungskosten-YYYY, garantie-aktiv, wichtig, langzeitarchiv
Themen-Tag (sparsam)	versicherungen, altersvorsorge, geldanlage, fahrrad, schule, küche, …

4.3 Storage Paths

10 Pfade, einer pro Lebensbereich + Sonderfall Anleitungen. Template-Schema:

{owner_username}/<Lebensbereich>/{created_year}/{correspondent}/{title}

Anleitungen ohne Jahr (zeitlose Referenz). Differenzierung von Person via Tags (robin/vincent), nicht via Sub-Pfade.

4.4 Correspondents

Namenskonventionen:

• Firmen mit offiziellem Namen
• Privatpersonen als „Nachname, Vorname”
• Ärzte als „Nachname, Vorname Dr. (Fachrichtung)”
• Behörden möglichst spezifisch (Finanzamt Köln-Altstadt statt nur Finanzamt)

Aktuell sind 88 von 121 Correspondents mit Literal- oder Regex-Match konfiguriert, der Rest läuft auf ML-basiertem Auto-Match.

---

5 Subdomain-Routing & TLS

Alle Services hängen unter *.mimir.dyn.veedel.net (intern-only, nicht öffentlich routbar). Synology Reverse Proxy (Anmeldeportal → Erweitert → Reverse Proxy) terminiert TLS und routet anhand des Hostnamens.

Subdomain	Ziel intern	Anmerkung
paperless.mimir.dyn.veedel.net	http://localhost:8010	Paperless-Container
sso.mimir.dyn.veedel.net	https://localhost:5001	DSM-Web, Pfade unter /webman/sso/
uptime.mimir.dyn.veedel.net	http://localhost:3002	Uptime Kuma
jellyfin.mimir.dyn.veedel.net	http://localhost:8096	Jellyfin
immich.mimir.dyn.veedel.net	http://localhost:2283	Immich

5.1 Wildcard-Zertifikat

Ein einziges Let’s-Encrypt-Zertifikat deckt alle Subdomains ab: *.mimir.dyn.veedel.net + mimir.dyn.veedel.net. Erneuerung erfolgt automatisch via acme.sh mit DNS-Challenge (TSIG gegen die BIND-Instanz, in der die dyn.veedel.net-Zone gehostet wird).

Default-CA: Let’s Encrypt (einmalig per acme.sh --set-default-ca --server letsencrypt gesetzt). Deploy-Hook: synology_dsm (ersetzt das Cert in DSM unattended).

---

6 Betrieb

6.1 Datei-Layout

Pfad	Inhalt
/volume1/docker/paperless/	docker-compose.yml, .env (Secrets)
/volume1/paperless/data/	Paperless-interne Daten (Index etc.)
/volume1/paperless/media/	Originaldokumente (Archiv)
/volume1/paperless/export/	Manuelle Exporte
/volume1/paperless/db17/	PostgreSQL-Volume
/volume1/paperless/db-backup/	Automatische DB-Dumps (alle 7 Tage)
/volume1/paperless/redis/	Redis-Persistenz
/volume1/Paperless-Inbox/<user>/	SMB-Upload pro User (Shared Folder)

6.2 Backups

• PostgreSQL: paperless-db-backup-Container macht alle 7 Tage einen pg_dump, hält die letzten 10 (in /volume1/paperless/db-backup/)
• Media-Files & Konfigurationen: Synology Hyper Backup auf externes Ziel (Backup-Job separat eingerichtet)
• .env mit Secrets: NICHT in Repo, in einem Passwort-Manager + manuell auf ein externes Medium gesichert
• Vollständige Wiederherstellung: DB-Dump einspielen → Media-Files zurückspielen → Container starten – getestet bisher nicht systematisch, sollte einmal als Drill durchgespielt werden

6.3 Wartung

Was	Frequenz	Wie
Eingang-Tag auf 0 ziehen	wöchentlich	Manuell in Paperless UI
Neue steuer-YYYY-Tags zum Jahreswechsel	jährlich	Paperless UI: Settings → Tags
Let’s-Encrypt-Cert-Renewal	alle 60 Tage	Automatisch (acme.sh + cron)
Container-Updates	quartalsweise	Manuell, DB-Backup zuerst
DSM-Updates	monatlich	Synology Update Manager
Schema-Doku aktualisieren	bei strukturellen Änderungen	Diese Notiz in Obsidian

6.4 Troubleshooting-Cheatsheet

Symptom	Erster Schritt
SSO-Login schlägt fehl	DSM-User aktiv? Gruppe paperless-users? SSO-Server-Logs im DSM-Log-Viewer
Paperless nicht erreichbar	docker compose logs webserver --tail 50; Container-Status prüfen
SMB-Upload kommt nicht an	/volume1/Paperless-Inbox/<user>/ prüfen; ACLs auf Subfolder
Owner wird nicht gesetzt	Workflow-Pfad-Filter prüfen (*/<user>/*); Trigger = Consumption Started
Cert abgelaufen	acme.sh --renew -d mimir.dyn.veedel.net --force; danach Deploy-Hook
DB-Backup wiederherstellen	pg_restore aus /volume1/paperless/db-backup/dump_*.psql
Bulk-Import-Race („File not found”)	INOTIFY_DELAY ist gesetzt – Errors sind kosmetisch wenn Dok in Paperless ankommt

---

7 API-Skripte (für Restore- und Migrations-Szenarien)

Skripte automatisieren Setup- und Migrationsarbeiten via Paperless-REST-API. Token-Konvention: über source ~/.paperless-env in die Shell laden, niemals im Klartext in Skripten oder Kommandozeile.

Skript	Zweck
create-doctypes.sh	Initiale Document Types anlegen
create-storage-paths.sh	Storage-Path-Templates anlegen
automatch.sh	Auto-Match-Patterns für Correspondents setzen
migrate-paths.sh	Dokumente auf neue Storage Paths umhängen (einmalige Migration)
cleanup-paths.sh	Alte (leere) Storage Paths löschen
tag-orphans.sh	Lebensbereich-Tags bei verwaisten Dokumenten ergänzen

Transclude of paperless-scripts.zip

8 Versionshistorie

Version	Datum	Änderung
1.0	2026-05-18	Initiale Schema-Doku Paperless-intern (Document Types, Tags, Storage Paths, Correspondents)
1.1	2026-05-20	Auth via Synology SSO Server, Subdomain-Routing, Family-User-Setup, Betriebsabschnitt