Angeregt durch aktuelle paperless-ngx Threads und einem Artikel auf neryarticles.com wollte ich paperless-ngx auch ausprobieren. Ich möchte paperless-ngx aber nicht als Web-Service auf einem Extra-Server (im Heimnetz oder gar in einer Cloud) haben. Die Papiere sollen auf meinem Rechner im verschlüsselten Homeverzeichnis bleiben.
Die Standard-Installation basiert auf Docker und Docker-Compose. Entweder man lädt eine von mehreren docker-compose.yml-Dateien von der paperless-ngx-Website herunter oder ein Installationsskript, das verschiedene Optionen abfragt und dann die passende docker-compose.yml-Datei lädt und anpasst.
Ich möchte aber zumindest auf meinen Fedora-Rechnern kein Docker installieren, sondern rootless-Container mit podman nutzen. Ich habe daher nach entsprechenden Anleitungen für die Installation von paperless-ngx in rootless Containern gesucht, aber nichts passendes gefunden. Teils waren die Anleitungen unnötig kompliziert, teils auch fehlerhaft. Hilfreich für mich war letztlich nur eine Antwort zu einem Issue auf der paperless-github Site: https://github.com/paperless-ngx/…discussions/686
Da die Kommandozeilen-Schnittstelle von podman weitgehend kompatibel zu docker ist, sollte es eigentlich möglich sein, die `docker-compose.yml` Dateien direkt in podman zu nutzen. Auf einem Fedora 42 System muss man dazu nur das Pendant zu docker-compose installieren:
dnf install podman-compose
Zu Vergleichszwecken habe ich zunächst docker, docker-compose und paperless-ngx auf Debian 12 mit dem Paperless-ngx Installationsskript installiert, einige Papiere importiert und dann die Docker-Konfigurationsdateien `docker-compose.yml`, `docker-compose.env` und `.env` auf meinen Fedora-Rechner in das gleiche Verzeichnis `~/Dokumente/paperless` kopiert. In der Theorie müsste man jetzt mit dem Kommando
podman compose pull
podman compose up
die paperless-Container starten können. In der Praxis waren noch folgende Anpassungen nötig, die ich nach einigen Fehlversuchen gefunden hatte:
In der Datei docker-compose.env die User- und Group-Id auf 0, d.h. auf root setzen. Mit podman läuft der Container mit den Rechten des aufrufenden Nutzers und die root-Id im Container wird standardmäßig auf die User-Id des Aufrufers auf dem Host abgebildet. Das braucht man für die Verzeichnisse `./consume` und `./export`, damit der Systemuser `paperless` vom paperless-ngx-Container darauf lesen und schreiben darf:
USERMAP_UID=0
USERMAP_GID=0
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu
PAPERLESS_SECRET_KEY='Some-Random*Code'Für die docker-compose.yml Datei waren folgende zwei Anpassungen nötig:
- Ein Name für den pod, z.B. name: paperless
- Ein Flag :z für die geteilten Volumes, z.B.: - ./export:/usr/src/paperless/export:z
Das :z Flag sorgt dafür, dass SELinux nicht den Zugriff durch den Container auf das Volume blockiert. Das braucht man natürlich nur für Systeme mit SELinux.
Achtung Falle: Die Flags :z und :Z haben eine unterschiedliche Bedeutung. :z steht für shared, während :Z privat bedeutet, d.h. die Dateien sind nur für den Container les- und schreibbar. Für den Datenaustausch muss klein-:z gewählt werden.
Meine Container-Konfiguration in docker-compose.yml mit sqlite-DB und ohne Tika sieht dann so aus:
name: paperless
services:
broker:
image: docker.io/library/redis:8
restart: unless-stopped
volumes:
- redisdata:/data
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:latest
restart: unless-stopped
depends_on:
- broker
ports:
- "8000:8000"
volumes:
- data:/usr/src/paperless/data
- ./media:/usr/src/paperless/media:z
- ./export:/usr/src/paperless/export:z
- ./consume:/usr/src/paperless/consume:z
env_file: docker-compose.env
environment:
PAPERLESS_REDIS: redis://broker:6379
volumes:
data:
redisdata:Die Installation auf einem zweiten Rechner bot dann auch die Gelegenheit das Backup und Restore zu testen. Das Einspielen einer Backup-Datei geht wie auf der paperless-ngx-Doku angegeben:
podman compose exec webserver document_importer ../export/export-2025-07-07.zip
Es war nicht nötig, vorher noch einen paperless-Superuser zu setzen, wie bei der Standard-Installation mit Skript.
Starten des paperless-ngx Service geht dann mit
cd ~/Dokumente/paperless && podman compose up
Stoppen entsprechend mit podman compose down.
Ich habe mir noch das Tool "Podman Desktop" von Flathub installiert, um paperless-ngx und ggf. weitere Container oder Pods mit einer GUI starten und stoppen zu können:
Das ist aber optional und Geschmackssache.
Noch 'ne Falle: `podman compose` ist eigentlich ein Wrapper, der je nach Konfiguration das Kommando `podman-compose` oder `docker-compose` aufruft. `docker-compose` gilt als Referenzimplementierung und wird vorrangig aufgerufen. Nach meiner Erfahrung verhalten sich die beiden Tools im Detail unterschiedlich. Das führt dann zu Problemen, wenn man einen Pod mit "podman-compose pull/up" erstellt hat und dann später aus Versehen mit docker-compose up/down/exec" zugreifen will. Deswegen sollte docker-compose nicht installiert werden, oder in `/etc/containers/containers.conf` `podman-compose` als Provider konfiguriert werden.
