30050 - Paperless-ngx — Dokumentenmanagement mit OCR
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/30050-paperless-ngx.md
Paperless-ngx — Dokumentenmanagement mit OCR
Cluster: PROD · Ordner
argocd/apps/prod/paperless-ngx/· URLhttps://paperless.prod.homeserver.kubectl-Befehle in diesem Doc gelten für den PROD-Cluster (Zugriff je Cluster).
Paperless-ngx digitalisiert Briefe, Rechnungen und Verträge per OCR und macht
sie volltextdurchsuchbar. Dokumente können per Scanner, Smartphone-Foto oder
E-Mail eingereicht werden — alles Weitere läuft automatisch.
Architektur
paperless.prod.homeserver → Traefik → paperless-ngx (Port 8000)
├── Redis Sidecar (localhost:6379)
├── PVC: data (20 Gi, nas)
├── PVC: media (50 Gi, nas)
├── PVC: consume (5 Gi, nas)
├── PVC: export (10 Gi, nas)
└── PVC: redis (1 Gi, nas)
- OCR-Sprachen: Deutsch + Englisch (konfigurierbar via
PAPERLESS_OCR_LANGUAGE) - Datenbank: SQLite (ausreichend für Home-Lab, keine externe DB nötig)
- Redis: als Sidecar-Container im selben Pod (Adresse:
localhost:6379)
Erster Start
Nach dem Deploy muss ein Admin-Account angelegt werden:
kubectl -n paperless-ngx exec -it deploy/paperless-ngx -- \
python3 manage.py createsuperuser
Danach ist die Web-UI unter https://paperless.prod.homeserver erreichbar.
Secret Key sichern
Der PAPERLESS_SECRET_KEY in values.yaml ist ein Platzhalter und muss
vor dem ersten produktiven Einsatz durch einen echten geheimen Wert ersetzt
werden. Empfohlen: SealedSecret anlegen.
# Zufälligen Key generieren:
python3 -c "import secrets; print(secrets.token_hex(50))"
# Als SealedSecret:
echo -n "<generated-key>" | kubeseal --raw \
--namespace paperless-ngx --name paperless-ngx-secret \
--from-file=/dev/stdin
Dann in values.yaml die Env-Variable auf einen secretKeyRef umstellen.
Dokumente einreichen
Consume-Ordner (automatisch)
Dateien im Consume-Verzeichnis werden automatisch verarbeitet. Der PVC
paperless-ngx-consume kann per kubectl cp befüllt werden:
kubectl -n paperless-ngx cp /lokale/datei.pdf \
$(kubectl -n paperless-ngx get pod -l app.kubernetes.io/name=paperless-ngx \
-o jsonpath='{.items[0].metadata.name}'):/usr/src/paperless/consume/
Web-Upload
Direkt über die Web-UI unter https://paperless.prod.homeserver/upload.
E-Mail-Import (optional)
Paperless kann E-Mails mit Anhängen automatisch abholen (IMAP). Konfiguration
in der Admin-UI unter Mail → E-Mail-Konten.
n8n-Integration
Mit n8n (https://n8n.prod.homeserver) lassen sich Paperless-Ereignisse
weiterverarbeiten, z. B.:
Neues Dokument in Paperless (Webhook)
→ Kategorisierung prüfen
→ ntfy-Push "📄 Neue Rechnung erkannt: {Titel}"
Paperless bietet eine REST-API unter https://paperless.prod.homeserver/api/.
Backup
# Export aller Dokumente (inkl. Metadaten):
kubectl -n paperless-ngx exec deploy/paperless-ngx -- \
document_exporter ../export
# Export-Verzeichnis lokal sichern:
kubectl -n paperless-ngx cp \
$(kubectl -n paperless-ngx get pod -l app.kubernetes.io/name=paperless-ngx \
-o jsonpath='{.items[0].metadata.name}'):/usr/src/paperless/export/ \
./paperless-backup/
Konfiguration (values.yaml)
| Key | Bedeutung | Default |
|---|---|---|
persistence.media.size |
Speicher für Originaldokumente | 50Gi |
persistence.data.size |
Datenbank + Thumbnails + Caches | 20Gi |
env.PAPERLESS_OCR_LANGUAGE |
Tesseract-Sprachcodes | deu+eng |
env.PAPERLESS_URL |
Öffentliche URL für Links | https://paperless.prod.homeserver |
resources.limits.memory |
RAM-Limit (OCR ist speicherhungrig) | 2Gi |
Fehlersuche
kubectl -n paperless-ngx get pods,pvc,ingress
kubectl -n paperless-ngx logs deploy/paperless-ngx -c paperless-ngx --tail=100
kubectl -n paperless-ngx logs deploy/paperless-ngx -c redis --tail=30
kubectl -n paperless-ngx exec deploy/paperless-ngx -- document_exporter ../export
| Symptom | Ursache | Lösung |
|---|---|---|
Pod Pending, PVC Pending |
StorageClass nas oder NAS nicht bereit (fünf PVCs: data, media, consume, export, redis) |
kubectl -n paperless-ngx describe pvc, NAS-Speicher |
Pod CreateContainerConfigError oder Start bricht ab (SECRET_KEY) |
SealedSecret für PAPERLESS_SECRET_KEY nicht entschlüsselt oder noch Platzhalter |
Abschnitt „Secret Key sichern“, Sealed Secrets |
Pod startet mehrfach neu (OOMKilled) |
OCR braucht mehr als das Limit (2 GiB) | resources.limits.memory erhöhen, PAPERLESS_TASK_WORKERS und PAPERLESS_THREADS_PER_WORKER (je 1) niedrig halten |
| Anmeldung unmöglich (kein Benutzer) | Admin-Account noch nicht angelegt | Abschnitt „Erster Start“, createsuperuser |
| Dokumente im Consume-Ordner werden nicht aufgenommen | Datei im falschen PVC oder Rechte (Benutzer 1000), Consumer-Fehler | Log lesen (consumer), Rechte im PVC prüfen, Abschnitt „Dokumente einreichen“ |
| OCR liefert falsche Sprache | PAPERLESS_OCR_LANGUAGE/PAPERLESS_OCR_LANGUAGES passt nicht |
auf deu+eng bzw. deu eng setzen |
Weboberfläche: falsche Links (http://…) |
PAPERLESS_URL falsch |
https://paperless.prod.homeserver |
| Seite nicht erreichbar | Ingress, DNS, NetworkPolicy (default-ingress lässt nur den Namespace selbst, kube-system und extraIngressNamespaces zu) |
kubectl -n paperless-ngx get ingress,networkpolicy, Namespace des Aufrufers (zum Beispiel n8n) in networkPolicy.extraIngressNamespaces eintragen |
| n8n erreicht Paperless nicht | NetworkPolicy blockt n8n | wie oben, Abschnitt „n8n-Integration“ |
Redis-Fehler im Log (Connection refused) |
Redis-Sidecar nicht bereit | kubectl logs … -c redis, PVC redis prüfen |
| Datenverlust-Sorge nach Neuaufbau | SQLite-DB liegt im PVC data, Dokumente im PVC media |
Abschnitt „Backup“ (Exporter), NAS-Backup |
| Dienst steht in PROD | Application heißt prod-paperless-ngx |
kubectl-Kontext PROD (a0010) |
Allgemeine Fehlersuche: zentrale Fehlersuche.