Paperless-ngx

Paperless-ngx ist das digitale Vereinsarchiv: Protokolle, Satzung, Verträge, Rechnungen und Versicherungsunterlagen werden gescannt, per Texterkennung durchsuchbar gemacht und automatisch einsortiert.

Was kann Paperless-ngx?

Texterkennung (OCR): Aus jedem Scan wird ein durchsuchbares PDF. Man findet das Protokoll von 2019 über ein Stichwort, nicht über den Ordnerpfad.
Automatische Zuordnung: Paperless lernt, welche Dokumente zu welchem Absender, Typ und Schlagwort gehören.
Eingangsordner und E-Mail: Was im Eingangsordner oder in einem Postfach landet, wird automatisch importiert.
Rechte: Benutzer und Gruppen sehen nur, was sie sehen sollen, etwa die Kasse nur Finanzunterlagen.

Der Container

Paperless bringt Texterkennung, Datenbank, Warteschlange und viele Hilfsprogramme mit. Von Hand installiert ist das mühsam, als Docker-Paket ist es ein Befehl. Deshalb ist Paperless einer der beiden Dienste, die bei mir mit Docker im Container laufen.

# auf dem Proxmox-Knoten
pct clone 9000 110 --hostname paperless --full
pct set 110 --cores 2 --memory 3072 --onboot 1 --features nesting=1,keyctl=1 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.178.40/24,gw=192.168.178.1
pct resize 110 rootfs 32G
pct start 110
pct exec 110 -- dpkg-reconfigure openssh-server

Für die Dokumente selbst lohnt sich ein eigener Datenträger auf dem Datenlaufwerk: unter Ressourcen → Hinzufügen → Mount Point, eingehängt unter /srv/paperless.

Docker installieren

Docker kommt aus dem offiziellen Docker-Repository, nicht aus den älteren Debian-Paketen:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker admin       # danach einmal neu anmelden
docker run --rm hello-world

Paperless installieren

Paperless besteht aus drei Docker-Containern: der Anwendung, einer PostgreSQL-Datenbank und Redis als Warteschlange für die Texterkennung.

# /opt/paperless/compose.yaml
services:
  broker:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${DB_PASSWORD}

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on: [db, broker]
    ports:
      - "8000:8000"
    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
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: ${DB_PASSWORD}
      PAPERLESS_SECRET_KEY: ${SECRET_KEY}
      PAPERLESS_URL: https://docs.meinverein.de
      PAPERLESS_TIME_ZONE: Europe/Berlin
      PAPERLESS_OCR_LANGUAGE: deu
      USERMAP_UID: 1000
      USERMAP_GID: 1000

volumes:
  pgdata:
  redisdata:

sudo mkdir -p /opt/paperless /srv/paperless/{data,media,export,consume}
sudo chown -R admin: /opt/paperless /srv/paperless
cd /opt/paperless

# Passwörter erzeugen
cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
SECRET_KEY=$(openssl rand -hex 32)
EOF

docker compose up -d
docker compose logs -f webserver     # warten, bis „Listening at …“ erscheint

# ersten Administrator anlegen
docker compose exec webserver createsuperuser

Im Reverse Proxy docs.meinverein.de auf http://192.168.178.40:8000 zeigen lassen, Zertifikat holen, fertig. Updates später mit docker compose pull && docker compose up -d, vorher einen Snapshot des Containers anlegen.

Einrichtung: erst denken, dann scannen

Paperless ist nur so gut wie seine Ordnung. Bevor der erste Stapel durch den Scanner geht, lege ich die Grundstruktur an:

Element	Bedeutung	Beispiele
Korrespondent	von wem / an wen	Finanzamt, Landesverband, Versicherung, Stadt
Dokumenttyp	was ist es	Protokoll, Vertrag, Rechnung, Bescheid, Satzung
Schlagwort	Querschnittsthemen	Vorstand, Kasse, Jugend, Bootshaus, Zuschuss
Speicherpfad	wie die Dateien intern abgelegt werden	`{{ created_year }}/{{ document_type }}/{{ title }}`

Wenige, klar definierte Dokumenttypen und Schlagworte sind besser als viele. Die Liste kommt in den Ablageplan des Vereins, damit alle gleich ablegen.

Wie Dokumente hineinkommen

Hochladen per Drag & Drop in der Weboberfläche oder per Smartphone-App.
Eingangsordner: Alles, was in /srv/paperless/consume landet, wird importiert. Den Ordner kann man per Samba im Netzwerk freigeben, viele Scanner speichern direkt dorthin.
E-Mail: Unter E-Mail ein Postfach wie archiv@meinverein.de hinterlegen. Anhänge werden automatisch importiert.
Anmeldung mit Vereinskonto: Wer Keycloak nutzt, bindet Paperless per OpenID Connect an.

Sicherung

Zusätzlich zum Proxmox-Backup erstellt Paperless einen eigenen, lesbaren Export aller Dokumente samt Metadaten. Den lasse ich nachts per Cron laufen (crontab -e):

0 2 * * * cd /opt/paperless && docker compose exec -T webserver document_exporter ../export