Paperless-ngx: Installation mit Docker Compose

Auf einen Blick

Gilt für	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.

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: grep -o -m1 sse4_2 /proc/cpuinfo.
• Speicher: Originale plus PDF/A-Archivversion – grob das Doppelte der Scan-Menge, zuzüglich Backup.
• Ein DNS-Name wie dms.firma.de 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

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

Seit Version 3 ist PAPERLESS_SECRET_KEY Pflicht. Er signiert Sitzungen und Token und gehört ins Backup.

Schritt 2: Paperless-ngx mit Docker Compose konfigurieren

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

• 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: deu+eng erkennt deutsche und englische Texte. Deutsch, Englisch, Französisch, Italienisch und Spanisch sind im Image enthalten, weitere über PAPERLESS_OCR_LANGUAGES.
• 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 latest, damit Updates bewusst erfolgen.

Schritt 3: Starten und Superuser anlegen

docker compose up -d
docker compose logs -f webserver        # warten, bis Migrationen durch sind
docker compose exec webserver createsuperuser

1. https://dms.firma.de aufrufen und mit dem Superuser anmelden.
2. Unter Mein Profil die Zwei-Faktor-Anmeldung einrichten.
3. 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.
4. Unter Einstellungen Sprache Deutsch, Datumsformat und Startseite wählen.
5. Ein Testdokument hochladen und unter Aufgaben bzw. Systemstatus prüfen, ob OCR, Tika und Gotenberg arbeiten.

Reverse Proxy

• Der Proxy leitet https://dms.firma.de auf http://127.0.0.1:8000 weiter, inklusive WebSocket-Verbindungen für die Statusanzeigen (/ws/).
• Die maximale Upload-Größe im Proxy anheben (z. B. nginx client_max_body_size 200M;), sonst scheitern große Scans.
• Seit Version 3 bestimmt die Anmeldebibliothek die Client-IP für die Ratenbegrenzung anders. Hinter einem Proxy PAPERLESS_TRUSTED_PROXIES 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 (docker network inspect). PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT 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

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

• 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 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

• Paperless-ngx Dokumentation: Setup
• Linux-Consulting von m.a.x. it

Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen