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.

Inhalt
Paperless-ngx 3.4.2PostgreSQL 18Valkey 9Caddy 2.11Docker 29.9Debian 13Paperless-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
- 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.
- Ein Benutzer mit
sudo-Rechten. - Eine Domain, zum Beispiel
{{domain}}, mit einem A-Record auf die IP-Adresse deines Servers. - 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:
curl -fsSL https://get.docker.com | sudo shPrüfe danach die Installation:
docker --versionFehlt 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:
mkdir -p ~/paperless/{data,media,export,consume,db,valkey}
cd ~/paperlessmediaenthält deine Dokumente,dataden Suchindex und die Einstellungen.exportnimmt später Backups auf.consumeist der Eingangsordner. Dateien, die dort erscheinen, übernimmt Paperless automatisch. Wie du ihn für Scanner freigibst, steht in der Scanner-Anleitung.dbundvalkeygehören den Datenbank-Containern.
Der Paperless-Container läuft mit der Benutzer-ID 1000. Prüfe, dass dein Benutzer diese ID hat:
id -uSteht 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:
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)
EOFZeige dir die Datei an und notiere das Admin-Passwort:
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:
nano compose.yamlservices:
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 mitredis://. 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.4zieht 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
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
sudo docker compose up -dBeim ersten Mal lädt Docker alle Images. Das dauert ein bis zwei Minuten. Danach prüfst du den Status:
sudo docker compose psWarte, bis beim Container paperless in der Spalte Status healthy steht. Die erste Initialisierung der Datenbank braucht etwas Zeit. Zum Beobachten:
sudo docker compose logs -f paperlessBeende 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:

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:
sudo docker compose exec paperless document_exporter ../exportIm 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:
sudo docker compose pull
sudo docker compose up -dDer 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.
Änderungsprotokoll
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.