imported>TechCorner-Redaktion: Neuer Artikel: Compose mit PostgreSQL, Valkey, Tika und Gotenberg, Pflichtwerte ab v3, OCR deutsch, Reverse Proxy, Updates

2026-10-17T00:00:00Z

Neuer Artikel: Compose mit PostgreSQL, Valkey, Tika und Gotenberg, Pflichtwerte ab v3, OCR deutsch, Reverse Proxy, Updates

← Nächstältere Version	Version vom 17. Oktober 2026, 00:00 Uhr
(kein Unterschied)

imported>TechCorner-Redaktion: Neuer Artikel: Compose mit PostgreSQL, Valkey, Tika und Gotenberg, Pflichtwerte ab v3, OCR deutsch, Reverse Proxy, Updates

2026-10-17T00:00:00Z

Neuer Artikel: Compose mit PostgreSQL, Valkey, Tika und Gotenberg, Pflichtwerte ab v3, OCR deutsch, Reverse Proxy, Updates

Neue Seite

{{Steckbrief
| gilt_fuer = Paperless-ngx 3.3.x als Docker-Container (ghcr.io/paperless-ngx/paperless-ngx) mit PostgreSQL 18, Valkey 9, Apache Tika und Gotenberg auf Linux, z. B. Debian 13 oder Ubuntu 24.04
| bereich = Server-Software
| dauer = ca. 1 Stunde
| rechte = Root bzw. Mitglied der Gruppe docker
| stand = Oktober 2026
}}
'''Paperless-ngx mit Docker Compose installieren''' ist der empfohlene Weg: Die Anwendung, eine PostgreSQL-Datenbank, Valkey als Nachrichtenvermittler sowie Tika und Gotenberg für Office-Dateien und E-Mails laufen als eigene Container. Diese Anleitung baut auf der offiziellen Compose-Vorlage auf, setzt die seit Version 3 vorgeschriebenen Werte, stellt die Texterkennung auf Deutsch ein und zeigt den ersten Start, den Betrieb hinter einem Reverse Proxy und den Ablauf von Updates.

[[Datei:Paperless-Installation.png|thumb|center|750px|Installation von Paperless-ngx mit Docker Compose: Container webserver (Port 8000) mit Ordnern data, media, consume und export; PostgreSQL 18, Valkey als Broker, Tika und Gotenberg für Office-Dateien und E-Mails; Pflichtwerte PAPERLESS_SECRET_KEY und PAPERLESS_DBENGINE seit Version 3, PAPERLESS_URL, OCR-Sprache deu+eng, Zeitzone Europe/Berlin, USERMAP_UID/GID; Superuser anlegen; Reverse Proxy mit HTTPS und PAPERLESS_TRUSTED_PROXIES; Updates mit festem Versions-Tag.]]

== Voraussetzungen ==
* Linux-Server oder VM mit '''Docker Engine''' und Compose-Plugin, siehe [[Docker]].
* '''Ressourcen''': 2–4 vCPU und 4–8 GB RAM für ein kleines Büro; OCR großer Scans ist rechenintensiv. Die CPU muss SSE4.2 unterstützen (praktisch jede CPU seit 2011), sonst stürzt der Klassifikator ab: <code>grep -o -m1 sse4_2 /proc/cpuinfo</code>.
* '''Speicher''': Originale plus PDF/A-Archivversion – grob das Doppelte der Scan-Menge, zuzüglich Backup.
* Ein '''DNS-Name''' wie <code>dms.firma.de</code> und ein Reverse Proxy mit Zertifikat, siehe [[Reverse Proxy]]. Paperless-ngx sollte nur im LAN bzw. per VPN erreichbar sein.

== Schritt 1: Verzeichnisse und Geheimnisse ==
<syntaxhighlight lang="bash">
sudo mkdir -p /opt/paperless/{consume,export} && cd /opt/paperless
cat > .env <<EOF
PG_PASSWORD=$(openssl rand -hex 24)
PAPERLESS_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(64))")
EOF
chmod 600 .env
</syntaxhighlight>
Seit Version 3 ist '''<code>PAPERLESS_SECRET_KEY</code> Pflicht'''. Er signiert Sitzungen und Token und gehört ins Backup.

== Schritt 2: Paperless-ngx mit Docker Compose konfigurieren ==
<syntaxhighlight lang="yaml">
services:
broker:
image: docker.io/valkey/valkey:9-alpine
restart: unless-stopped
volumes:
- ./redisdata:/data

db:
image: docker.io/library/postgres:18
restart: unless-stopped
volumes:
- ./pgdata:/var/lib/postgresql
environment:
POSTGRES_DB: paperless
POSTGRES_USER: paperless
POSTGRES_PASSWORD: ${PG_PASSWORD}

webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:3.3.2
restart: unless-stopped
depends_on: [db, broker, gotenberg, tika]
ports:
- "127.0.0.1:8000:8000"
volumes:
- ./data:/usr/src/paperless/data
- ./media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export
- ./consume:/usr/src/paperless/consume
environment:
PAPERLESS_REDIS: redis://broker:6379
PAPERLESS_DBENGINE: postgresql
PAPERLESS_DBHOST: db
PAPERLESS_DBPASS: ${PG_PASSWORD}
PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
PAPERLESS_URL: https://dms.firma.de
PAPERLESS_TRUSTED_PROXIES: 172.18.0.1
PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT: 1
PAPERLESS_TIME_ZONE: Europe/Berlin
PAPERLESS_OCR_LANGUAGE: deu+eng
PAPERLESS_TIKA_ENABLED: 1
PAPERLESS_TIKA_ENDPOINT: http://tika:9998
PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
USERMAP_UID: 1000
USERMAP_GID: 1000

gotenberg:
image: docker.io/gotenberg/gotenberg:8.37
restart: unless-stopped
command:
- "gotenberg"
- "--chromium-disable-javascript=true"
- "--chromium-allow-list=^file:///tmp/.*"

tika:
image: docker.io/apache/tika:3.3.1.0
restart: unless-stopped
</syntaxhighlight>
* '''PAPERLESS_DBENGINE''' ist seit Version 3 für PostgreSQL und MariaDB Pflicht.
* '''PAPERLESS_URL''' setzt zugleich erlaubte Hostnamen und vertrauenswürdige Ursprünge (CSRF). Ohne den richtigen Wert schlagen Anmeldung und Speichern hinter dem Proxy fehl.
* '''OCR-Sprache''': <code>deu+eng</code> erkennt deutsche und englische Texte. Deutsch, Englisch, Französisch, Italienisch und Spanisch sind im Image enthalten, weitere über <code>PAPERLESS_OCR_LANGUAGES</code>.
* '''USERMAP_UID/GID''': auf den Benutzer setzen, dem der Eingangsordner auf dem Host gehört – sonst fehlen Schreibrechte.
* '''Tika und Gotenberg''' wandeln Word-, Excel- und E-Mail-Dateien in PDF um. Die Gotenberg-Parameter verhindern, dass beim Umwandeln von E-Mails JavaScript oder externe Inhalte (Tracking-Pixel) geladen werden.
* '''Feste Versionen''' statt <code>latest</code>, damit Updates bewusst erfolgen.

== Schritt 3: Starten und Superuser anlegen ==
<syntaxhighlight lang="bash">
docker compose up -d
docker compose logs -f webserver # warten, bis Migrationen durch sind
docker compose exec webserver createsuperuser
</syntaxhighlight>
# <code>https://dms.firma.de</code> aufrufen und mit dem Superuser anmelden.
# Unter ''Mein Profil'' die Zwei-Faktor-Anmeldung einrichten.
# Für die tägliche Arbeit ein '''normales Benutzerkonto''' anlegen; der Superuser sieht alle Dokumente und ist nur für die Verwaltung gedacht, siehe [[Paperless-ngx: Benutzer, Berechtigungen und Absicherung]].
# Unter ''Einstellungen'' Sprache Deutsch, Datumsformat und Startseite wählen.
# Ein Testdokument hochladen und unter ''Aufgaben'' bzw. ''Systemstatus'' prüfen, ob OCR, Tika und Gotenberg arbeiten.

== Reverse Proxy ==
* Der Proxy leitet <code>https://dms.firma.de</code> auf <code>http://127.0.0.1:8000</code> weiter, inklusive WebSocket-Verbindungen für die Statusanzeigen (<code>/ws/</code>).
* Die '''maximale Upload-Größe''' im Proxy anheben (z. B. nginx <code>client_max_body_size 200M;</code>), sonst scheitern große Scans.
* Seit Version 3 bestimmt die Anmeldebibliothek die Client-IP für die Ratenbegrenzung anders. Hinter einem Proxy <code>PAPERLESS_TRUSTED_PROXIES</code> auf die IP-Adresse setzen, mit der der Proxy bei Paperless ankommt – läuft er auf demselben Host, ist das die Gateway-Adresse des Docker-Netzes (<code>docker network inspect</code>). <code>PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT</code> ist die Zahl der Proxy-Stationen, meist 1; ohne diesen Wert setzt Paperless die Anzahl der eingetragenen Adressen ein. Falsche Werte führen zu '''403 Forbidden''' beim Login.
* Beispiele: [[OPNsense - Caddy Reverse Proxy]], [[Nginx]].

== Updates ==
<syntaxhighlight lang="bash">
cd /opt/paperless
docker compose exec -T webserver document_exporter ../export # Backup, siehe Backup-Artikel
# Tag in compose.yaml anheben, dann:
docker compose pull && docker compose up -d && docker compose logs --tail 100 webserver
</syntaxhighlight>
* Datenbankmigrationen laufen beim Start automatisch.
* '''Umstieg von Version 2 auf 3''' nur von '''2.20.15''' aus. Vorher den Migrationsleitfaden lesen: neue Pflichtwerte, geänderte OCR- und Eingangsordner-Einstellungen, neu aufgebauter Suchindex. Details in [[Paperless-ngx: Backup, Updates und GoBD im Unternehmen]].
* Bei Hauptversionen von PostgreSQL ist ein Dump und Neuimport nötig; das Daten-Volume der Datenbank wird nicht automatisch migriert.

== Hinweise ==
* '''SQLite''' funktioniert für Tests und Einzelplätze, für mehrere Benutzer PostgreSQL wählen.
* '''Ohne Tika''' werden nur PDF, Bilder und Textdateien verarbeitet. Für Word-Dokumente und E-Mail-Dateien ist es nötig.
* Bei Aufbau und Betrieb von Linux-Servern und Containern unterstützt Sie das [https://www.max-it.de/it-services/linux-consulting/ Linux-Consulting von m.a.x. it].

== Siehe auch ==
* [[Paperless-ngx]] – Überblick und alle Artikel der Reihe
* [[Paperless-ngx: Dokumente erfassen – Scanner, E-Mail und Barcodes]]
* [[PostgreSQL]]
* [[Redis]]

== Links und Quellen ==
* [https://docs.paperless-ngx.com/setup/ Paperless-ngx Dokumentation: Setup]
* [https://www.max-it.de/it-services/linux-consulting/ Linux-Consulting von m.a.x. it]

{{Uebermax}}
[[Kategorie:Server-Software]]

Paperless-ngx: Installation mit Docker Compose - Versionsgeschichte

imported>TechCorner-Redaktion: Neuer Artikel: Compose mit PostgreSQL, Valkey, Tika und Gotenberg, Pflichtwerte ab v3, OCR deutsch, Reverse Proxy, Updates

imported>TechCorner-Redaktion: Neuer Artikel: Compose mit PostgreSQL, Valkey, Tika und Gotenberg, Pflichtwerte ab v3, OCR deutsch, Reverse Proxy, Updates