Paperless-ngx mit Docker installieren¶

Veröffentlicht am 7. August 2026 · Geschätzte Lesezeit: 5 Minuten

Paperless-ngx macht gescannte Briefe und Rechnungen durch OCR durchsuchbar und legt Dokumente mit Schlagwörtern, Absendern und Dokumenttypen ab. Die Dateien bleiben auf deinem eigenen Server. Für Installation und ersten Dokumenttest solltest du etwa 30 bis 45 Minuten einplanen.

Voraussetzungen

Ein Linux-Server mit Docker und Docker Compose
Mindestens 2 GB freier Arbeitsspeicher und ausreichend Speicher für Dokumente
Eine feste IP-Adresse oder DHCP-Reservierung für den Server
curl und Python 3 auf dem Server

1. Arbeitsordner anlegen¶

Führe den folgenden Befehl im Terminal des Docker-Servers aus. Er legt einen eigenen Ordner für Paperless-ngx an:

sudo mkdir -p /opt/paperless-ngx

Gib den Ordner anschließend deinem angemeldeten Benutzer. Ersetze <benutzer> durch deinen Linux-Benutzernamen:

sudo chown -R <benutzer>:<benutzer> /opt/paperless-ngx

Wechsle in den Arbeitsordner:

cd /opt/paperless-ngx

2. Offizielle Compose-Dateien laden¶

Lade die aktuelle PostgreSQL-Compose-Datei direkt aus dem offiziellen Projekt. Sie richtet Paperless-ngx, PostgreSQL und Redis gemeinsam ein:

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

Lade die zugehörige Konfigurationsdatei:

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

Die kleine .env-Datei sorgt für einen eindeutigen Namen der Docker-Volumes:

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

Dateien vor späteren Updates vergleichen

Überschreibe deine angepassten Dateien bei einem Update nicht blind. Die offiziellen Vorlagen können sich ändern. Sichere sie und vergleiche Änderungen, bevor du eine neue Vorlage übernimmst.

3. Geheimen Schlüssel erzeugen¶

Die Vorlage enthält nur einen unsicheren Beispielwert. Dieser Befehl erzeugt lokal einen zufälligen Schlüssel, trägt ihn in docker-compose.env ein und entfernt die Shell-Variable danach wieder:

secret="$(python3 -c 'import secrets; print(secrets.token_urlsafe(64))')" && sed -i "s|^PAPERLESS_SECRET_KEY=.*|PAPERLESS_SECRET_KEY=$secret|" docker-compose.env && unset secret

Prüfe nur, ob die Zeile vorhanden ist, ohne den Schlüssel auf dem Bildschirm auszugeben:

grep -q '^PAPERLESS_SECRET_KEY=.' docker-compose.env && echo "Geheimer Schlüssel ist gesetzt"

Schlüssel nicht weitergeben

Der Schlüssel schützt Sitzungen und signierte Daten. Veröffentliche die Datei docker-compose.env nicht und speichere sie zusammen mit deiner Sicherung.

4. Sprache und Zeitzone einstellen¶

Füge deutsche Zeitzone und deutsche OCR-Erkennung an die Konfigurationsdatei an:

printf '\nPAPERLESS_TIME_ZONE=Europe/Berlin\nPAPERLESS_OCR_LANGUAGE=deu\n' >> docker-compose.env

PAPERLESS_OCR_LANGUAGE=deu legt Deutsch als Standardsprache für die Texterkennung fest. Die offizielle Container-Vorlage enthält die deutsche Tesseract-Sprache bereits.

5. Container starten¶

Lade die benötigten Images und starte alle Dienste. Führe beide Befehle im Ordner /opt/paperless-ngx aus:

docker compose pull

docker compose up -d

Prüfe, ob broker, db und webserver laufen:

docker compose ps

Die ersten Datenbankmigrationen können einige Minuten dauern. Beobachte bei Bedarf das Protokoll:

docker compose logs -f webserver

Beende die laufende Protokollanzeige mit Strg+C. Die Container laufen weiter.

6. Administratorkonto anlegen¶

Dieser Befehl wird im Paperless-Webcontainer ausgeführt und fragt Benutzername, E-Mail-Adresse und Passwort interaktiv ab:

docker compose exec webserver createsuperuser

Verwende ein langes, einzigartiges Passwort. Gib keine echten Zugangsdaten in die Compose-Datei oder in kopierte Befehle ein.

7. Oberfläche öffnen und testen¶

Öffne im Browser:

http://<server-ip>:8000

Ersetze <server-ip> durch die IP-Adresse deines Docker-Servers. Melde dich mit dem soeben erstellten Administratorkonto an. Lade zum Test eine unkritische PDF-Datei über die Oberfläche hoch. Nach der Verarbeitung sollte ihr Text durchsuchbar sein.

Dokumentenarchiv schützen

Leite Port 8000 nicht direkt aus dem Internet weiter. Dokumente enthalten oft besonders sensible Daten. Nutze für externen Zugriff ein VPN oder einen HTTPS-Reverse-Proxy mit zusätzlicher Zugriffsbeschränkung.

8. Dokumente über den Eingangsordner importieren¶

Die offizielle Compose-Datei bindet den Ordner /opt/paperless-ngx/consume ein. Kopiere ein Dokument dorthin, damit Paperless-ngx es automatisch einliest:

cp <datei.pdf> /opt/paperless-ngx/consume/

Ersetze <datei.pdf> durch den vollständigen Pfad deiner PDF-Datei. Verwende zuerst nur eine Kopie, bis du geprüft hast, wie deine Installation mit Originaldateien umgeht.

9. Sicherung und Rückweg einrichten¶

Der offizielle Dokumentexport enthält Dokumente, Vorschaubilder, Metadaten und den Datenbankinhalt. Starte ihn im Arbeitsordner mit:

docker compose exec -T webserver document_exporter ../export

Das Ergebnis liegt danach unter /opt/paperless-ngx/export. Sichere zusätzlich docker-compose.yml, docker-compose.env und .env verschlüsselt auf einem zweiten Datenträger. Prüfe regelmäßig, ob im Export eine manifest.json und Dokumentdateien vorhanden sind.

Version beim Wiederherstellen beachten

Ein Export sollte mit derselben Paperless-ngx-Version importiert werden, mit der er erstellt wurde. Notiere deshalb die laufende Version oder sichere die verwendete Image-Angabe zusammen mit dem Export. API-Token sind nicht enthalten und müssen nach einem Import neu erstellt werden.

Für einen sicheren Rückweg stoppst du den aktuellen Stack, benennst den Arbeitsordner um und richtest eine leere Installation mit passender Version ein. Lege den Export in deren Ordner export und importiere ihn erst in die leere Installation.

10. Aktualisieren¶

Prüfe vor einem Update die offiziellen Versions- und Migrationshinweise und erstelle einen Export. Stoppe dann den Stack:

docker compose down

Lade die aktuellen Images und starte Paperless-ngx wieder:

docker compose pull
docker compose up -d

Prüfe danach Oberfläche und Protokoll:

docker compose logs --tail=100 webserver

11. Typische Fehler beheben¶

Bleibt die Oberfläche leer, warte zunächst auf das Ende der Datenbankmigrationen und prüfe den Zustand:

docker compose ps
docker compose logs --tail=100 webserver db broker

Ist Port 8000 bereits belegt, ändere in docker-compose.yml beim Dienst webserver die Portzeile beispielsweise auf:

    ports:
      - "8010:8000"

Danach erreichst du die Oberfläche unter http://<server-ip>:8010. Kann Paperless keine Dateien aus consume lesen, prüfe Besitz und Rechte des Ordners. Setze bei Bedarf USERMAP_UID und USERMAP_GID in docker-compose.env auf die Kennungen deines Linux-Benutzers; du findest sie mit id.

12. Quellen und Video¶

Fertig¶

Paperless-ngx läuft jetzt mit PostgreSQL und Redis auf deinem Docker-Server. Melde dich unter http://<server-ip>:8000 an, lade eine Test-PDF hoch und suche nach einem Wort aus dem Dokument. Wird die Datei gefunden, arbeiten Import, OCR und Suche wie erwartet.