Deployn

Paperless-ngx auf einem VPS installieren: Docker, Caddy und Valkey

Paperless-ngx 3 auf einem Debian-13-VPS installieren: Docker Compose mit PostgreSQL, Valkey und Tika, HTTPS über Caddy, Backup und Update, Schritt für Schritt.

Paperless-ngx auf einem VPS installieren: Docker, Caddy und Valkey hero image
Inhalt
Getestet mit
Paperless-ngx 3.4.2PostgreSQL 18Valkey 9Caddy 2.11Docker 29.9Debian 13
Zuletzt geprüft am

Paperless-ngx ist ein Dokumentenmanagementsystem, das du selbst betreibst. Du scannst oder lädst Briefe, Rechnungen und Verträge hoch, Paperless erkennt den Text und legt alles durchsuchbar ab. Mit Paperless-Hosting auf einem eigenen Server (VPS) erreichst du dein Archiv von überall, ohne dass ein Cloud-Anbieter deine Dokumente sieht.

Hier installiere ich Paperless-ngx 3 auf einem Debian-13-Server mit Docker Compose. Dazu gehören PostgreSQL als Datenbank, Valkey als Message-Broker, Tika und Gotenberg für Office-Dokumente und Caddy für HTTPS. Am Ende läuft alles unter https://{{domain}}.

Wer lieber ein NAS nutzt, findet hier die Anleitung für Synology. Einen Überblick über Funktionen, Kosten und Alternativen gibt dir der Paperless-ngx-Guide.

Voraussetzungen

  1. Ein Server mit Debian 13. Ich nutze einen VPS von Hetzner vom Typ CAX11 mit 2 Kernen und 4 GB RAM. Der Stack belegt im Leerlauf rund 1,2 GB Arbeitsspeicher, 4 GB geben dir Luft für die Texterkennung. Mit 2 GB geht es auch, dann solltest du Swap einrichten. Ein VPS bei netcup (Affiliate-Link) eignet sich genauso.
  2. Ein Benutzer mit sudo-Rechten.
  3. Eine Domain, zum Beispiel {{domain}}, mit einem A-Record auf die IP-Adresse deines Servers.
  4. Offene Ports 80 und 443. Port 22 brauchst du für SSH.

Docker installieren

Verbinde dich per SSH mit dem Server und installiere Docker mit dem offiziellen Skript:

Terminalbash
curl -fsSL https://get.docker.com | sudo sh

Prüfe danach die Installation:

Terminalbash
docker --version

Fehlt curl, installierst du es vorher mit sudo apt install -y curl.

Ordner anlegen

Lege ein Verzeichnis für Paperless an, mit je einem Unterordner für Daten, Dokumente, Export, Consume-Ordner, Datenbank und Valkey:

Terminalbash
mkdir -p ~/paperless/{data,media,export,consume,db,valkey}
cd ~/paperless
  • media enthält deine Dokumente, data den Suchindex und die Einstellungen.
  • export nimmt später Backups auf.
  • consume ist der Eingangsordner. Dateien, die dort erscheinen, übernimmt Paperless automatisch. Wie du ihn für Scanner freigibst, steht in der Scanner-Anleitung.
  • db und valkey gehören den Datenbank-Containern.

Der Paperless-Container läuft mit der Benutzer-ID 1000. Prüfe, dass dein Benutzer diese ID hat:

Terminalbash
id -u

Steht dort eine andere Zahl, setzt du unten in der .env die Werte USERMAP_UID und USERMAP_GID auf deine Zahl.

Zugangsdaten erzeugen

Paperless braucht einen geheimen Schlüssel, ein Datenbankpasswort und ein Passwort für den ersten Benutzer. Erzeuge sie mit openssl, damit du nichts selbst ausdenken musst. Der folgende Block schreibt die .env gleich fertig:

Terminalbash
cat > .env <<EOF
PAPERLESS_URL=https://{{domain}}
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=$(openssl rand -hex 16)
USERMAP_UID=1000
USERMAP_GID=1000
POSTGRES_PASSWORD=$(openssl rand -hex 16)
EOF

Zeige dir die Datei an und notiere das Admin-Passwort:

Terminalbash
cat .env
Variable Bedeutung
PAPERLESS_URL Die öffentliche Adresse. Ohne sie lehnt Paperless Anmeldungen über HTTPS ab.
PAPERLESS_SECRET_KEY Geheimer Schlüssel für Sitzungen. Nie weitergeben.
PAPERLESS_OCR_LANGUAGE Sprachen der Texterkennung. deu+eng erkennt Deutsch und Englisch.
PAPERLESS_ADMIN_USER, PAPERLESS_ADMIN_PASSWORD Legt beim ersten Start einen Administrator an.
POSTGRES_PASSWORD Passwort der Datenbank.

Die Datei enthält Geheimnisse. Gib sie nie weiter und committe sie in kein Git-Repository.

Die compose.yaml

Erstelle die Datei:

Terminalbash
nano compose.yaml
yaml
services:
    broker:
        image: valkey/valkey:9
        container_name: paperless-valkey
        restart: unless-stopped
        volumes:
            - ./valkey:/data

    db:
        image: postgres:18
        container_name: paperless-db
        restart: unless-stopped
        volumes:
            - ./db:/var/lib/postgresql
        environment:
            POSTGRES_DB: paperless
            POSTGRES_USER: paperless
            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

    gotenberg:
        image: gotenberg/gotenberg:8.38
        container_name: paperless-gotenberg
        restart: unless-stopped
        command:
            - "gotenberg"
            - "--chromium-disable-javascript=true"
            - "--chromium-allow-list=^file:///tmp/.*"

    tika:
        image: apache/tika:3.3.1.0
        container_name: paperless-tika
        restart: unless-stopped

    paperless:
        image: ghcr.io/paperless-ngx/paperless-ngx:3.4
        container_name: paperless
        restart: unless-stopped
        depends_on:
            - db
            - broker
            - gotenberg
            - tika
        env_file: .env
        environment:
            PAPERLESS_REDIS: redis://broker:6379
            PAPERLESS_DBHOST: db
            PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}
            PAPERLESS_TIKA_ENABLED: 1
            PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
            PAPERLESS_TIKA_ENDPOINT: http://tika:9998
        volumes:
            - ./data:/usr/src/paperless/data
            - ./media:/usr/src/paperless/media
            - ./export:/usr/src/paperless/export
            - ./consume:/usr/src/paperless/consume

    caddy:
        image: caddy:2
        container_name: caddy
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        volumes:
            - ./Caddyfile:/etc/caddy/Caddyfile
            - caddy_data:/data
            - caddy_config:/config

volumes:
    caddy_data:
    caddy_config:

Speichern mit Strg+O, Enter, schließen mit Strg+X.

Das macht jeder Dienst:

  • broker ist Valkey, ein Redis-kompatibler Zwischenspeicher für die Aufgabenwarteschlange. Paperless nennt die Einstellung weiterhin PAPERLESS_REDIS, die Adresse beginnt mit redis://. Das ist so gewollt, das Protokoll ist identisch.
  • db ist PostgreSQL 18. Seit Version 18 liegt der Datenordner unter /var/lib/postgresql, nicht mehr unter /var/lib/postgresql/data.
  • gotenberg und tika wandeln Word-, Excel- und E-Mail-Dateien in PDFs um. Ohne sie nimmt Paperless nur PDFs und Bilder an.
  • paperless ist die Anwendung. Der Tag 3.4 zieht immer die neueste Version der Reihe 3.4.x.
  • caddy nimmt Anfragen auf 80 und 443 an und holt Zertifikate von Let’s Encrypt.

Paperless selbst veröffentlicht keinen Port. Nur Caddy ist von außen erreichbar.

Die Caddyfile

Terminalbash
nano Caddyfile
{{domain}} {
    reverse_proxy paperless:8000
}

Caddy leitet Anfragen an den Paperless-Container weiter. HTTPS richtet es selbst ein, sobald der DNS-Eintrag auf den Server zeigt.

Starten

Terminalbash
sudo docker compose up -d

Beim ersten Mal lädt Docker alle Images. Das dauert ein bis zwei Minuten. Danach prüfst du den Status:

Terminalbash
sudo docker compose ps

Warte, bis beim Container paperless in der Spalte Status healthy steht. Die erste Initialisierung der Datenbank braucht etwas Zeit. Zum Beobachten:

Terminalbash
sudo docker compose logs -f paperless

Beende die Ausgabe mit Strg+C. Fehler siehst du dort sofort. Häufig ist es ein falscher Domainname oder ein fehlender DNS-Eintrag, dann kann Caddy kein Zertifikat holen. Das siehst du mit sudo docker compose logs caddy.

Anmelden

Öffne https://{{domain}} im Browser. Melde dich mit Benutzer admin und dem Passwort aus der .env an.

Ändere danach sofort das Passwort: Klicke oben rechts auf deinen Namen, dann auf Mein Profil. Dort aktivierst du außerdem die Zwei-Faktor-Authentifizierung. Die Zeile PAPERLESS_ADMIN_PASSWORD in der .env wirkt nur beim ersten Start. Du kannst sie danach löschen.

Lege für den Alltag einen eigenen Benutzer an (Einstellungen → Benutzer & Gruppen) und nutze den Administrator nur für die Verwaltung.

Das erste Dokument

Klicke auf Hochladen oder ziehe eine PDF in das Browserfenster. Paperless liest die Datei, erkennt den Text und legt eine durchsuchbare Kopie an. Nach einigen Sekunden erscheint das Dokument in der Liste:

Dokumentenliste von Paperless-ngx 3 mit Karten, Tags und Korrespondenten

Wie du neue Dokumente automatisch einsortierst, zeige ich in den Workflows. Für eine lesbare Ablage auf der Festplatte siehst du Speicherpfade und Ordnerstruktur.

Server absichern

Ein öffentlich erreichbarer Server mit sensiblen Dokumenten verdient etwas Sorgfalt:

  • Firewall: Erlaube nur die Ports 22, 80 und 443. Bei Hetzner stellst du das in der Cloud-Firewall ein. Docker umgeht lokale Firewalls wie ufw, weil es eigene Regeln anlegt. Verlasse dich deshalb auf die Firewall des Anbieters.
  • SSH: Melde dich per Schlüssel an und schalte die Passwort-Anmeldung ab.
  • Zwei-Faktor: Aktiviere sie in Paperless für jeden Benutzer.
  • Updates: Halte Debian und die Images aktuell, siehe unten.
  • Zugriff einschränken: Wer Paperless nur selbst nutzt, kann den Zugriff auf ein VPN wie WireGuard oder Tailscale beschränken und Port 443 gar nicht öffnen.

Backup

Backups sind bei Dokumenten Pflicht. Der eingebaute Exporter schreibt alle Dokumente und Metadaten in den Ordner export:

Terminalbash
sudo docker compose exec paperless document_exporter ../export

Im Ordner export liegen danach die Originale, Thumbnails und eine manifest.json mit den Metadaten. Sichere diesen Ordner an einen anderen Ort, am besten außerhalb des Servers. Wie du den Export automatisierst, steht in Paperless Backup und Restore und im Ofelia-Backup.

Ein Backup, das du nie zurückgespielt hast, ist nicht getestet. Probiere die Wiederherstellung auf einem zweiten Server aus.

Aktualisieren

Aktualisiere im Ordner ~/paperless die Images und starte neu:

Terminalbash
sudo docker compose pull
sudo docker compose up -d

Der Tag 3.4 liefert alle Patch-Versionen der Reihe 3.4 automatisch. Für einen Wechsel auf eine neue Reihe, etwa 3.5, änderst du den Tag in der compose.yaml. Lies vorher die Release Notes und mach ein Backup.

Die Hauptversion von PostgreSQL ersetzt du nie einfach im Tag. Dafür ist eine Migration nötig, wie sie dieser Beitrag beschreibt.

Typische Fehler

Die Seite lädt nicht oder zeigt eine Zertifikatswarnung. Der DNS-Eintrag zeigt nicht auf den Server, oder Port 80 ist geschlossen. Caddy braucht beides, um das Zertifikat zu holen.

Die Anmeldung schlägt mit “CSRF” fehl. PAPERLESS_URL stimmt nicht mit der Adresse im Browser überein. Prüfe Schreibweise und https://.

Der Container paperless startet immer wieder neu. Schau ins Log. Häufig fehlen Rechte im Ordner data oder media. Setze sie auf deinen Benutzer, zum Beispiel mit sudo chown -R 1000:1000 data media export consume.

Office-Dateien werden abgelehnt. Prüfe, ob die Container tika und gotenberg laufen und die drei PAPERLESS_TIKA_*-Einstellungen in der compose.yaml stehen.

FAQ

Häufige Fragen

Wie viel RAM braucht Paperless-ngx?

Der komplette Stack mit PostgreSQL, Valkey, Tika, Gotenberg und Caddy belegt im Leerlauf rund 1,2 GB. Plane 4 GB ein, damit die Texterkennung bei größeren Dokumenten genug Luft hat. Mit 2 GB geht es mit Swap.

Warum Valkey statt Redis?

Valkey ist ein freier Fork von Redis und spricht dasselbe Protokoll. Paperless-ngx funktioniert damit unverändert. Die Einstellung heißt weiterhin PAPERLESS_REDIS.

Brauche ich Tika und Gotenberg?

Nur, wenn du Word-, Excel-, PowerPoint- oder E-Mail-Dateien ablegen willst. Für PDFs und Bilder reichen Paperless, Datenbank und Broker.

Wie ändere ich das Admin-Passwort?

Melde dich an, öffne oben rechts Mein Profil und ändere dort das Passwort. Die Variable PAPERLESS_ADMIN_PASSWORD wirkt nur beim ersten Start.

Wie aktualisiere ich Paperless-ngx?

Im Ordner mit der compose.yaml führst du sudo docker compose pull und danach sudo docker compose up -d aus. Mach vorher ein Backup mit document_exporter.

Kann ich Paperless-ngx ohne Domain betreiben?

Ja, aber nur im lokalen Netz oder über ein VPN. Für HTTPS über Caddy und Let's Encrypt brauchst du eine Domain.

Teilen
XRedditE-Mail
Zurück zu allen Beiträgen

Änderungsprotokoll

  1. Komplett neu geschrieben für Paperless-ngx 3.4: Debian 13, Docker Compose mit PostgreSQL 18 und Valkey 9 statt Redis, Caddy ohne WireGuard, Zugangsdaten per openssl, Backup mit document_exporter, Update-Hinweise und Härtung des Servers.

Weiter in dieser Reihe

Kommentare