Paperless-ngx auf Ubuntu einrichten

Paperless-ngx ist eine leistungsstarke Open-Source-Lösung für digitales Dokumentenmanagement. Damit kannst du Rechnungen, Verträge, Briefe und andere Unterlagen automatisch erfassen, per OCR durchsuchbar machen und sauber archivieren.

In dieser Anleitung richten wir Paperless-ngx auf einem Ubuntu Server mit Docker Compose ein, inklusive PostgreSQL, Redis, sinnvollen Verzeichnisstrukturen und einer sauberen Veröffentlichung hinter einem Reverse Proxy.

1. Voraussetzungen

• Ubuntu Server 22.04 oder neuer
• Root- oder Sudo-Zugriff
• Docker und Docker Compose Plugin
• Genügend Speicherplatz für Dokumente, Vorschaudateien und Datenbank
• Optional eine Domain wie docs.example.com für HTTPS-Zugriff

Für neue Installationen empfiehlt das Projekt bei Docker Compose ausdrücklich PostgreSQL als Datenbank. Das übernehmen wir auch hier.

2. Arbeitsverzeichnis anlegen

Lege zunächst ein eigenes Verzeichnis für Paperless-ngx an:

mkdir -p ~/paperless-ngx
cd ~/paperless-ngx

Danach erstellen wir direkt die wichtigsten Unterordner für Dokumente, Import, Export und Anwendungsdaten:

sudo mkdir -p /srv/paperless/{consume,media,export,data}
sudo chown -R $USER:$USER /srv/paperless

Die Ordner haben dabei folgende Aufgaben:

• consume: Eingang für neue Dokumente
• media: verwaltete Dokumente und Dateien
• export: Exporte aus Paperless-ngx
• data: interne Anwendungsdaten

3. Offizielle Compose-Datei vorbereiten

Paperless-ngx stellt offizielle Docker-Compose-Templates bereit. Für eine neue Installation mit PostgreSQL erstellen wir eine saubere lokale docker-compose.yml auf Basis des empfohlenen Setups:

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless
    volumes:
      - pgdata:/var/lib/postgresql/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless
      PAPERLESS_URL: https://docs.example.com
      USERMAP_UID: 1000
      USERMAP_GID: 1000
    volumes:
      - /srv/paperless/data:/usr/src/paperless/data
      - /srv/paperless/media:/usr/src/paperless/media
      - /srv/paperless/export:/usr/src/paperless/export
      - /srv/paperless/consume:/usr/src/paperless/consume

volumes:
  pgdata:
  redisdata:

Speichere die Datei als docker-compose.yml.

Hinweis: Wenn dein Benutzer nicht die UID/GID 1000 hat, prüfe sie mit folgenden Befehlen:

id -u
id -g

Setze die Werte dann entsprechend in der Compose-Datei, damit Container und Host korrekt auf das Consumption-Verzeichnis schreiben können.

4. Sicherheits- und Basiswerte anpassen

Vor dem ersten Start solltest du mindestens folgende Werte anpassen:

• POSTGRES_PASSWORD auf ein eigenes starkes Passwort
• PAPERLESS_DBPASS identisch zum PostgreSQL-Passwort setzen
• PAPERLESS_URL auf deine Ziel-Domain anpassen, z. B. https://docs.example.com

Wenn du Paperless-ngx zunächst nur lokal testen willst, kannst du den Dienst auch ohne Domain starten und den Reverse Proxy später ergänzen. Für den produktiven Betrieb ist die feste URL aber sinnvoll.

5. Container starten

Starte jetzt den Stack im Hintergrund:

docker compose pull
docker compose up -d

Prüfe danach den Status:

docker compose ps

Falls etwas nicht hochkommt, helfen die Logs:

docker compose logs -f

6. Erster Zugriff und Superuser

Nach dem Start erreichst du Paperless-ngx direkt über Port 8000:

http://10.0.0.5:8000

Beim ersten Zugriff wirst du aufgefordert, einen Superuser anzulegen. Verwende dafür ein starkes Passwort und idealerweise später einen separaten Alltagsbenutzer für die tägliche Nutzung.

Das Projekt weist selbst darauf hin, dass Superuser vollständigen Zugriff auf alle Dokumente und Objekte haben. Für den Alltag ist ein normaler Benutzer oft sinnvoller.

7. Reverse Proxy mit eigener Domain

Für den produktiven Betrieb solltest du Paperless-ngx über eine eigene Domain mit HTTPS veröffentlichen. Mit Caddy könnte das so aussehen:

docs.example.com {
    reverse_proxy localhost:8000
}

Danach erreichst du dein Dokumentenarchiv sauber unter:

https://docs.example.com

Achte darauf, dass PAPERLESS_URL in deiner Compose-Datei zu dieser Domain passt, sonst können Links und Weiterleitungen später unsauber werden.

8. Dokumente automatisch konsumieren

Einer der größten Vorteile von Paperless-ngx ist das automatische Verarbeiten neuer Dateien. Alles, was du in das Consumption-Verzeichnis legst, wird vom System erkannt und importiert:

cp meine-rechnung.pdf /srv/paperless/consume/

Danach OCRt Paperless das Dokument, analysiert Inhalt und Metadaten und legt es in der Bibliothek ab.

Wichtig: Wenn dein Consumption-Verzeichnis auf einem Dateisystem ohne inotify liegt, etwa auf manchen NFS-Freigaben, funktioniert die Standardüberwachung nicht zuverlässig. In solchen Fällen musst du Polling aktivieren.

9. Sinnvolle erste Einstellungen

Nach dem ersten Login solltest du dir besonders diese Punkte anschauen:

• Benutzer und Berechtigungen
• Korrespondenten, Tags und Dokumenttypen
• E-Mail-Import, falls du Dokumente per Mail empfangen willst
• OCR- und Spracheinstellungen
• Backup-Konzept für Dokumente und Datenbank

Gerade Tags, Korrespondenten und automatische Regeln machen Paperless-ngx mit der Zeit extrem stark. Es lohnt sich, diese Struktur früh sauber aufzubauen.

10. Updates einspielen

Updates kannst du in der Regel so durchführen:

cd ~/paperless-ngx
docker compose pull
docker compose up -d

Prüfe danach wieder kurz Status und Logs:

docker compose ps
docker compose logs --tail=50

Vor größeren Updates solltest du immer ein Backup der Dokumente und der PostgreSQL-Daten haben.

11. Backups und Sicherheit

Für ein verlässliches Backup-Konzept solltest du mindestens diese Bereiche sichern:

• /srv/paperless/media mit deinen eigentlichen Dokumenten
• /srv/paperless/data mit internen Anwendungsdaten
• die PostgreSQL-Daten aus dem Volume oder per Datenbank-Dump

Nur Dateien ohne Datenbank oder nur Datenbank ohne Dokumente reichen im Ernstfall nicht. Plane deshalb beides konsequent mit ein.

12. Fazit

Mit Paperless-ngx bekommst du ein sehr starkes selbst gehostetes Dokumentenarchiv, das weit über simples Dateispeichern hinausgeht. OCR, automatische Klassifizierung, Tags und Suche machen das System im Alltag extrem nützlich.

Wenn du Rechnungen, Verträge, Garantiescheine oder andere Unterlagen endlich sauber digital organisieren willst, ist Paperless-ngx auf Ubuntu eine der besten Lösungen überhaupt.

Tipp:
Kombiniere Paperless-ngx mit einem Scanner, einem Consumption-Ordner und einem guten Backup-Konzept. Dann wird daraus schnell eines der praktischsten Systeme in deinem Homelab.