Papierstapel raus: Paperless-ngx mit Docker Compose sauber selbst hosten

Wenn Rechnungen, Garantien, Verträge und Lieferscheine nur halb sortiert in Ordnern und Downloads herumliegen, wird jede spätere Suche unnötig teuer. Paperless-ngx ist dafür eine der praktischsten Self-Hosting-Lösungen überhaupt: Dokumente landen in einem Web-Archiv, werden per OCR durchsuchbar und lassen sich mit Tags, Korrespondenten und Dokumenttypen organisieren.

Für diesen Guide ist die wichtige Grundlage klar: Die aktuelle offizielle Dokumentation von Paperless-ngx empfiehlt für Docker-Compose-Setups die bereitgestellten Compose-Dateien des Projekts, nennt http://127.0.0.1:8000 als Standardzugriff und dokumentiert für Updates weiter den Weg über docker compose pull und docker compose up -d. Für neue Docker-Installationen ist das stabiler und sinnvoller als ein improvisiertes Compose-File aus irgendeinem Blog.

Was du am Ende hast

Ein laufendes Paperless-ngx-Setup im Browser unter http://localhost:8000
PostgreSQL als Datenbank statt eines schnellen SQLite-Provisoriums
OCR für deutschsprachige Dokumente
Einen klaren Import-Pfad für neue PDFs und Scans
Ein Update- und Backup-Kommando, das du später direkt weiterverwenden kannst

Voraussetzungen

Docker Engine und docker compose sind installiert
Du hast einen dedizierten Arbeitsordner, in dem das Setup leben darf
Deine Dokumente liegen als PDF oder Scan-Datei vor

1. Projektordner anlegen

Arbeite nicht irgendwo zwischen alten Compose-Dateien, sondern in einem sauberen Ordner:

mkdir paperless-ngx && cd paperless-ngx

Damit erfüllst du direkt die wichtigste Docker-Hygiene: Das Projekt bleibt in sich geschlossen, und du weißt später sofort, wo consume, export und die Compose-Dateien liegen.

2. Die offiziellen Compose-Dateien herunterladen

Paperless-ngx pflegt fertige Compose-Dateien selbst. Für dieses Setup nehmen wir die PostgreSQL-Variante aus dem offiziellen Repository und speichern sie lokal als Standarddatei.

curl -L \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml \
  -o docker-compose.yml

curl -L \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env \
  -o docker-compose.env

curl -L \
  https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env \
  -o .env

Die offizielle PostgreSQL-Datei bringt genau die drei Dienste mit, die du für einen sauberen Start brauchst:

webserver für Paperless-ngx selbst
db für PostgreSQL
broker für Redis

Außerdem bindet die Vorlage direkt die lokalen Ordner consume und export ein und veröffentlicht Paperless standardmäßig auf Port 8000.

3. Die Umgebungsdatei sinnvoll anpassen

Die Datei paperless-ngx/docker-compose.env ist der wichtigste Hebel für ein brauchbares Setup. Für einen deutschen Home-Server oder Büro-Rechner sind diese Einstellungen ein guter Start:

USERMAP_UID=1000
USERMAP_GID=1000
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu
PAPERLESS_SECRET_KEY=ersetze-diesen-wert-durch-einen-langen-zufallsstring

Wichtige Punkte dazu:

USERMAP_UID und USERMAP_GID sorgen dafür, dass du auf dem Host sauber auf den consume-Ordner schreiben kannst.
PAPERLESS_TIME_ZONE=Europe/Berlin verhindert unnötige Zeitstempel-Verwirrung.
PAPERLESS_OCR_LANGUAGE=deu ist für deutschsprachige Rechnungen und Briefe der richtige erste Schritt.
PAPERLESS_SECRET_KEY sollte kein Platzhalter bleiben, wenn das Setup länger als nur fünf Minuten leben soll.

Wenn du deine UID und GID nicht kennst, prüfst du sie lokal so:

id

Wenn du später Office-Dokumente wie .docx oder .odt automatisch verarbeiten willst, verweist die offizielle Doku auf die -tika-Compose-Varianten. Für einen reinen PDF- und Scan-Start ist die PostgreSQL-Vorlage ohne Zusatzdienste der bessere, schlankere Einstieg.

4. Container ziehen und Stack starten

Jetzt holst du die aktuellen Images und startest das Setup im Hintergrund:

docker compose pull
docker compose up -d

Die offiziellen Compose-Dateien referenzieren ghcr.io/paperless-ngx/paperless-ngx:latest. Laut aktueller Administrations-Doku steht latest dabei für den jeweils neuesten stabilen Stand.

5. Im Browser öffnen und den ersten Benutzer anlegen

Nach dem Start sollte Paperless unter http://localhost:8000 erreichbar sein. Öffne die Adresse im Browser und richte deinen ersten Benutzer ein.

Paperless-ngx Localhost Login

Wenn du lieber erst im Terminal prüfst, ob der Stack sauber hochgekommen ist:

docker compose ps
docker compose logs --tail=100 webserver
curl -I http://localhost:8000

Der sichtbare Endpunkt dieses Tutorials ist damit klar: Du landest auf der Weboberfläche und kannst Dokumente importieren, verschlagworten und durchsuchen.

6. Das erste Dokument importieren

Das offizielle Compose-Setup mountet lokal einen Ordner namens consume. Alles, was dort landet, kann Paperless automatisch übernehmen.

Lege also testweise eine PDF-Datei in paperless-ngx/consume:

cp ~/Downloads/rechnung.pdf ./consume/

Danach beobachtest du die Verarbeitung live:

docker compose logs -f webserver

Wenn OCR und Import sauber durchlaufen, taucht das Dokument kurz darauf in der Weboberfläche auf. Genau hier zeigt Paperless-ngx seinen Wert: Statt Dateinamen-Chaos bekommst du Volltextsuche, Tags, Dokumenttypen und einen festen Archivort.

7. Die zwei Kommandos, die du dir merken solltest

Update

Die offizielle Update-Dokumentation beschreibt für Docker den klassischen Weg:

docker compose down
docker compose pull
docker compose up -d

Das reicht in normalen Fällen, weil neue Migrationen beim Start mitgezogen werden.

Export-Backup

Paperless dokumentiert für Docker Compose auch einen eingebauten Exporter. Der praktische Befehl dafür lautet:

docker compose exec -T webserver document_exporter ../export

Damit landet ein verwertbarer Export in deinem lokalen Ordner paperless-ngx/export. Für ein privates Dokumentenarchiv ist das die Backup-Funktion, die du nicht vergessen solltest.

8. Was du danach sinnvoll als Nächstes tust

Lege Dokumenttypen wie Rechnung, Vertrag und Garantie an
Vergebe Tags nach Jahr oder Haushalt, statt alles in einen großen Haufen zu kippen
Scanne neue Unterlagen konsequent direkt in paperless-ngx/consume
Hänge das Setup erst dann hinter eine Domain oder einen Reverse Proxy, wenn lokal alles sauber läuft

Fazit

Paperless-ngx ist eines dieser seltenen Self-Hosting-Projekte, die sofort echten Alltagsnutzen liefern. Mit den offiziellen Compose-Dateien, PostgreSQL als Basis und einem sauber konfigurierten consume-Ordner hast du in kurzer Zeit ein Dokumentenarchiv, das nicht nur hübsch im Browser steht, sondern bei der nächsten Steuerfrage oder Garantiesuche ganz konkret Zeit spart.

Wenn du heute nur ein Docker-Projekt mit sichtbarem Ergebnis aufsetzt, ist dieses hier deutlich stärker als der nächste austauschbare Demo-Stack.

User Dashboard