Schlagwortarchiv für: Paperless-ngx

Beiträge

Paperless-ngx Docker Upgrade: von 2.20.15 auf 3.0.4

Paperless-ngx Docker Upgrade: von 2.20.15 auf 3.0.4

Paperless-ngx 3.0 bringt Breaking Changes. Diese Anleitung zeigt das Upgrade einer Docker-Installation, Schritt für Schritt.

Voraussetzung: Ausgangsversion muss 2.20.15 sein. Nur von dort aus ist der Sprung auf 3.0 offiziell unterstützt. Ältere Versionen zuerst auf 2.20.15 bringen.

Was sich in 3.0 ändert

  • Suchindex wechselt von Whoosh zu Tantivy (Rust). Volltextindex muss neu aufgebaut werden, passiert im Docker-Image automatisch beim Start.
  • PAPERLESS_SECRET_KEY ist jetzt Pflicht.
  • PAPERLESS_DBENGINE ist bei PostgreSQL/MariaDB jetzt Pflicht (vorher aus PAPERLESS_DBHOST abgeleitet).
  • Diverse SSL-/Timeout-/Pooling-Variablen der DB entfallen zugunsten von PAPERLESS_DB_OPTIONS.
  • API-Version 1 fällt weg.
  • Dokument-Prüfsummen wechseln auf SHA-256.
  • Datenbankmigrationen sind nicht rückwärtskompatibel. Ohne Backup kein Rollback.

Vollständige Liste: github.com/paperless-ngx/paperless-ngx/releases

Schritt 1: Backup

cd /opt/paperless

docker compose stop

# Datenbank (Beispiel PostgreSQL)
docker compose exec -T db pg_dump -U paperless paperless > /opt/backup/paperless-db-$(date +%F).sql

# Volumes sichern
sudo tar -czf /opt/backup/paperless-data-$(date +%F).tar.gz ./data
sudo tar -czf /opt/backup/paperless-media-$(date +%F).tar.gz ./media

# Compose-Files sichern
cp docker-compose.yml /opt/backup/docker-compose.yml.bak
cp docker-compose.env /opt/backup/docker-compose.env.bak

Alternativ den eingebauten Paperless-Exporter nutzen:

docker compose run --rm webserver document_exporter ../export

Schritt 2: Secret Key setzen

Falls bisher kein PAPERLESS_SECRET_KEY gesetzt war, lief 2.x mit einem eingebauten Default-Key. Für 3.0 wird ein expliziter Key Pflicht.

openssl rand -base64 64

In docker-compose.env oder direkt in docker-compose.yml unter environment eintragen:

YAML Datei
PAPERLESS_SECRET_KEY: "<generierter-wert>"

Wichtig: Wird ein neuer, zufälliger Key gesetzt statt des alten Default-Keys, werden bestehende Sessions und API-Tokens ungültig. Nutzer müssen sich neu anmelden.

Schritt 3: Datenbank-Engine explizit setzen

Nur bei PostgreSQL oder MariaDB nötig, nicht bei SQLite.

YAML Datei

# v2 (PostgreSQL wurde aus PAPERLESS_DBHOST abgeleitet)
PAPERLESS_DBHOST: postgres

# v3 (Engine muss explizit gesetzt sein)
PAPERLESS_DBENGINE: postgresql
PAPERLESS_DBHOST: postgres

Zulässige Werte: postgresql oder mariadb. Bisherige einzelne SSL-/Timeout-/Pooling-Variablen durch PAPERLESS_DB_OPTIONS ersetzen, falls verwendet:

YAML Datei
PAPERLESS_DB_OPTIONS: "sslmode=require,pool.max_size=20"

Alte Variablen funktionieren übergangsweise weiter, loggen aber eine Deprecation-Warnung beim Start.

Schritt 4: Image-Tag auf 3.0.4 setzen

In docker-compose.yml:

YAML Datei
services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15

ändern zu:

YAML Datei

services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.0.4

Wer bisher :latest nutzt: :latest zeigt seit Juli 2026 bereits auf 3.x. Für kontrollierte Major-Upgrades empfiehlt sich grundsätzlich ein fester Versions-Tag statt :latest.

Schritt 5: Neues Image ziehen und Container neu erstellen

docker compose pull
docker compose up -d

Der Suchindex-Rebuild (Whoosh → Tantivy) läuft beim ersten Start automatisch im Container. Bei größeren Archiven dauert das spürbar.

Schritt 6: Logs beobachten

docker compose logs -f webserver

Auf Migrationsfehler, fehlende Env-Variablen oder Reindex-Fortschritt achten.

Schritt 7: Verifikation

  • Version in der Weboberfläche prüfen (Systemstatus zeigt 3.0.4).
  • Volltextsuche testen, auch nach Umlauten und mehreren Suchbegriffen (Tantivy verknüpft Begriffe standardmäßig mit OR statt AND wie zuvor Whoosh).
  • Ein Testdokument einscannen/konsumieren lassen, OCR-Ergebnis prüfen.
  • Download und Vorschau eines bestehenden Dokuments prüfen.
  • Login/API-Token testen, falls der Secret Key neu gesetzt wurde.
  • Containerstatus prüfen: docker compose ps.

Rollback

Bei Problemen:

docker compose down

Alten Image-Tag (2.20.15) in docker-compose.yml zurücksetzen, DB-Dump aus Schritt 1 einspielen, data/ und media/ aus dem Backup zurückkopieren, dann:

docker compose up -d

Bekannte Stolperfallen

  • Fehlender PAPERLESS_SECRET_KEY bricht den Start ab.
  • PAPERLESS_DBENGINE vergessen bei PostgreSQL/MariaDB führt zu Verbindungsfehlern.
  • Zusätzliche, verwaiste Container aus älteren Compose-Setups können mit dem neuen Consumer kollidieren.
  • Veraltete Syntax in globalen Dateinamensvorlagen kann nach dem Upgrade Fehler werfen.

Quelle: github.com/paperless-ngx/paperless-ngx/releases

Paperless-ngx Upgrade: von 2.20.15 auf 3.0.4 (Debian-VM auf Proxmox)

Paperless-ngx Upgrade: von 2.20.15 auf 3.0.4 (Debian-VM auf Proxmox)

Paperless-ngx 3.0 bringt Breaking Changes. Diese Anleitung zeigt das Bare-Metal-Upgrade auf einer Debian-VM unter Proxmox, Schritt für Schritt.

Voraussetzung: Ausgangsversion muss 2.20.15 sein. Nur von dort aus ist der Sprung auf 3.0 offiziell unterstützt. Ältere Versionen zuerst auf 2.20.15 bringen.

Was sich in 3.0 ändert

  • Suchindex wechselt von Whoosh zu Tantivy (Rust). Volltextindex muss neu aufgebaut werden.
  • PAPERLESS_SECRET_KEY ist jetzt Pflicht.
  • PAPERLESS_DBENGINE ist bei PostgreSQL/MariaDB jetzt Pflicht (vorher aus PAPERLESS_DBHOST abgeleitet).
  • Diverse SSL-/Timeout-/Pooling-Variablen der DB entfallen zugunsten von PAPERLESS_DB_OPTIONS.
  • API-Version 1 fällt weg.
  • Dokument-Prüfsummen wechseln auf SHA-256.
  • Consumer-/OCR-Variablen teils umbenannt, OCR_MODE=skip-Verhalten ändert sich.
  • Datenbankmigrationen sind nicht rückwärtskompatibel. Ohne Backup kein Rollback.

Schritt 1: Snapshot der Proxmox-VM

Vor allem anderen: VM-Snapshot in Proxmox erstellen. Das ist der schnellste Rollback-Weg, unabhängig vom Applikations-Backup. Backup wichtig! Es kann immer was schief laufen!

qm snapshot <VMID> pre-paperless-3-0-4

Schritt 2: Anwendungs-Backup

Zusätzlich zum Snapshot ein Paperless-eigenes Backup, da die DB-Migration nicht reversibel ist.

sudo systemctl stop paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

# Datenbank (Beispiel PostgreSQL)
sudo -u postgres pg_dump paperless > /opt/backup/paperless-db-$(date +%F).sql

# Daten- und Medienverzeichnisse
sudo tar -czf /opt/backup/paperless-media-$(date +%F).tar.gz /opt/paperless/media
sudo tar -czf /opt/backup/paperless-data-$(date +%F).tar.gz /opt/paperless/data

# Konfiguration
sudo cp /opt/paperless/paperless.conf /opt/backup/paperless.conf.bak

Bei SQLite genügt eine Kopie der .sqlite3-Datei aus dem Datenverzeichnis.

Schritt 3: Version prüfen

cd /opt/paperless
sudo -Hu paperless git describe --tags

Muss v2.20.15 zeigen. Falls nicht: erst dorthin updaten, dann weiter.

Schritt 4: Secret Key sichern/setzen

Falls bisher kein PAPERLESS_SECRET_KEY gesetzt war, lief 2.x mit einem eingebauten Default-Key. Für 3.0 wird ein expliziter Key Pflicht.

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

Wert in paperless.conf eintragen:

ini
PAPERLESS_SECRET_KEY=<generierter-wert>

Wichtig: Wird ein neuer, zufälliger Key gesetzt statt des alten Default-Keys, werden bestehende Sessions und API-Tokens ungültig. Nutzer müssen sich neu anmelden.

Schritt 5: Datenbank-Engine explizit setzen

Nur bei PostgreSQL oder MariaDB nötig, nicht bei SQLite.

ini
PAPERLESS_DBENGINE=postgresql
PAPERLESS_DBHOST=postgres

Zulässige Werte: postgresql oder mariadb. Bisherige einzelne SSL-/Timeout-/Pooling-Variablen durch PAPERLESS_DB_OPTIONS ersetzen, falls verwendet, z. B.:

ini
PAPERLESS_DB_OPTIONS=sslmode=require,pool.max_size=20

Alte Variablen funktionieren übergangsweise weiter, loggen aber eine Deprecation-Warnung beim Start.

Schritt 6: Systemabhängigkeiten aktualisieren

bash
sudo apt update
sudo apt install --only-upgrade python3 python3-pip python3-dev imagemagick fonts-liberation \
  gnupg libpq-dev default-libmysqlclient-dev pkg-config libmagic-dev mime-support \
  libzbar0 poppler-utils unpaper ghostscript icc-profiles-free qpdf liblept5 \
  libxml2 pngquant zlib1g tesseract-ocr

Ergänzend benötigte OCR-Sprachpakete (tesseract-ocr-deu etc.) prüfen, falls sich Sprachvorgaben geändert haben.

Schritt 7: Dienste stoppen

Falls Schritt 2 nicht schon erledigt:

sudo systemctl stop paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

Schritt 8: Quellcode auf 3.0.4 bringen

cd /opt/paperless
sudo -Hu paperless git fetch --all --tags
sudo -Hu paperless git checkout tags/v3.0.4

Schritt 9: Python-Abhängigkeiten aktualisieren

Venv aktivieren und Requirements neu installieren:

sudo -Hu paperless bash -c '
  source /opt/paperless/venv/bin/activate
  pip install --upgrade pip
  pip install -r requirements.txt
'

Danach die installierten Pakete gegen die neue requirements.txt abgleichen und nicht mehr benötigte Pakete entfernen, um Konflikte zu vermeiden.

Schritt 10: Datenbankmigration

cd /opt/paperless/src
sudo -Hu paperless ../venv/bin/python3 manage.py migrate

Schritt 11: Statische Dateien und Suchindex

sudo -Hu paperless ../venv/bin/python3 manage.py collectstatic --clear --no-input
sudo -Hu paperless ../venv/bin/python3 manage.py document_index reindex --if-needed

Der --if-needed-Flag prüft Schema-Version und Sprach-Sentinels und baut den Tantivy-Index nur neu, wenn nötig. Bei größeren Archiven (mehrere zehntausend Dokumente) dauert das spürbar; Fortschritt im Log beobachten.

Schritt 12: Dienste starten

sudo systemctl start paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue
sudo systemctl status paperless-webserver

Schritt 13: Verifikation

  • Version in der Weboberfläche prüfen (Systemstatus zeigt 3.0.4).
  • Volltextsuche testen, auch nach Umlauten und mehreren Suchbegriffen (Tantivy verknüpft Begriffe standardmäßig mit OR statt AND wie zuvor Whoosh).
  • Ein Testdokument einscannen/konsumieren lassen, OCR-Ergebnis prüfen.
  • Download und Vorschau eines bestehenden Dokuments prüfen.
  • Login/API-Token testen, falls der Secret Key neu gesetzt wurde.
  • Log auf Fehler prüfen: journalctl -u paperless-webserver -n 200.

Rollback

Bei Problemen: Dienste stoppen, VM-Snapshot aus Schritt 1 zurückspielen. Alternativ Git-Checkout auf v2.20.15, DB-Dump aus Schritt 2 einspielen, altes paperless.conf zurückkopieren, Venv-Requirements der 2.20.15 neu installieren.

Bekannte Stolperfallen

  • Fehlender PAPERLESS_SECRET_KEY bricht den Start ab.
  • PAPERLESS_DBENGINE vergessen bei PostgreSQL/MariaDB führt zu Verbindungsfehlern.
  • Veraltete Syntax in globalen Dateinamensvorlagen kann nach dem Upgrade Fehler werfen.
  • Zusätzliche, nicht mehr benötigte Container/Prozesse aus älteren Setups können mit dem neuen Consumer kollidieren.

Paperless-ngx v2.20.14: Neues Update für das papierlose Büro

Paperless-ngx v2.20.14: Das nächste Level der digitalen Archivierung

Die Verwaltung von Briefen, Rechnungen und Verträgen kann eine zeitraubende Aufgabe sein. Doch mit dem Release von Paperless-ngx v2.20.14 festigt die Community-getriebene Software ihren Status als beste Open-Source-Lösung für das Dokumentenmanagement (DMS).

Warum Paperless-ngx ein Muss für das Home-Office ist

Paperless-ngx verwandelt einen Stapel Papier in ein durchsuchbares digitales Archiv. Das System überwacht einen Ordner auf deinem Server, führt eine optische Zeichenerkennung (OCR) durch und nutzt maschinelles Lernen, um Dokumente zu kategorisieren.

Die Neuerungen in Version v2.20.14:

  1. Gezielte Fehlerbehebung: In diesem Maintenance-Release wurden spezifische Probleme beim PDF-Parsing und in der Benutzeroberfläche behoben, was die Zuverlässigkeit im Alltag massiv erhöht.

  2. Optimierte Texterkennung: Die Integration von Tesseract OCR wurde weiter verfeinert, um auch bei schwierigen Scans präzise Ergebnisse zu liefern.

  3. Verbesserte Metadaten-Verarbeitung: Das Handling von Datumsangaben und automatischen Zuweisungen wurde präziser gestaltet.

  4. Einfaches Update: Dank Docker-Support ist der Wechsel auf die v2.20.14 in wenigen Minuten erledigt – ein einfacher Pull des Images genügt.

Fazit: Ein robustes Werkzeug für die digitale Freiheit

Paperless-ngx v2.20.14 zeigt einmal mehr, wie lebendig und wichtig dieses Projekt ist. Es ist die ideale Lösung für alle, die Wert auf Datenschutz legen und ihre Dokumente nicht in einer fremden Cloud, sondern auf der eigenen Hardware (NAS, Raspberry Pi oder Server) wissen wollen.

Zum Release-Log: Paperless-ngx v2.20.14 auf GitHub

Paperless-ngx – Update nicht möglich (Error response from daemon: unauthorized)

,

Falls ihr euren Docker Container updaten wollt und beim Pull folgenden Fehler bekommt:

Error response from daemon: Head "``https://ghcr.io/v2/paperless-ngx/tika/manifests/latest``": unauthorized

Um den Fehler zu beheben, müsst ihr die docker-compose.yml bearbeiten:

tika:
# image: ghcr.io/paperless-ngx/tika:latest
image: docker.io/apache/tika:latest
container_name: tika
restart: unless-stopped

 

Danach passt alles wieder:

root@paperless:/home/paperless# docker compose pull
[+] Pulling 45/45
✔ db Pulled 124.9s
✔ gotenberg Pulled 2.8s
✔ webserver Pulled 284.8s
✔ broker Pulled 281.5s
✔ tika Pulled 282.1s
root@paperless:/home/paperless# docker compose up -d
[+] Running 6/6
✔ Network paperless_default Created 29.7s
✔ Container tika Started 1.6s
✔ Container broker Started 1.6s
✔ Container paperless-gotenberg-1 Started 1.6s
✔ Container db Started 1.7s
✔ Container webserver Started 1.4s

Paperless-ngx in Proxmox als LXC-Container installieren – Step-by-Step Anleitung

,

 

Du möchtest dein Dokumentenmanagement mit Paperless-ngx selbst hosten? In diesem Tutorial zeige ich dir, wie du Paperless-ngx in einem LXC-Container auf Proxmox VE installierst – schlank, performant und vollständig unter deiner Kontrolle.

Voraussetzungen

  • Proxmox VE (7.x oder 8.x)

  • Root-Zugriff auf den Server

  • Container-Template: Ubuntu 22.04 empfohlen

  • mind. 2 GB RAM & 1 CPU-Kern

  • Optional: externes NAS oder Verzeichnis für Dokumente

Schritt 1: LXC-Container erstellen

Im Proxmox Webinterface:

  1. Neuen CT anlegen

  2. Template: ubuntu-22.04-standard_*.tar.zst

  3. Hostname: paperless

  4. CPU: mind. 1 Core

  5. RAM: mind. 2048 MB (mehr bei vielen Dokumenten)

  6. Netzwerk: statische IP oder DHCP

  7. Festplatte: 10–20 GB (je nach Nutzung)

⚠️ Aktiviere unter “Options” → “Features”:

  • Nesting

  • Fuse

Schritt 2: Container starten & vorbereiten

Per Konsole oder SSH verbinden:

apt update && apt upgrade -y
apt install -y curl wget git docker.io docker-compose

Docker aktivieren:

systemctl enable docker
systemctl start docker

Optional neuen User anlegen:

adduser paperless
usermod -aG docker paperless

Schritt 3: Paperless-ngx via Docker Compose installieren

Wechsle in ein passendes Verzeichnis:

mkdir -p /opt/paperless
cd /opt/paperless

Beispiel docker-compose.yml:

version: "3.4"

services:
  broker:
    image: redis:7
    restart: always

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: always

  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: always
    ports:
      - 8000:8000
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - export:/usr/src/paperless/export
      - consume:/usr/src/paperless/consume
    depends_on:
      - db
      - broker

volumes:
  data:
  media:
  export:
  consume:
  db_data:

Dann starten:

docker compose up -d

Schritt 4: Paperless-ngx aufrufen & einrichten

Nach ein paar Sekunden erreichst du Paperless im Browser:

http://<IP_DES_CONTAINERS>:8000

Erster Login:

Benutzername: admin

Passwort: admin (wird beim ersten Start generiert, ggf. selbst setzen!)

Du kannst auch via ENV-Variablen eigene Benutzer beim ersten Start anlegen – siehe die Paperless-ngx Dokumentation.

Schritt 5: Dokumente ablegen und verarbeiten

Lade PDFs in das Verzeichnis consume/, z. B.:

scp dokument.pdf root@<IP>:/opt/paperless/consume/

Paperless importiert sie automatisch und erstellt OCR-Texte.

 

Dokumententypen

 

Updates & Neustart

Zum Aktualisieren:

cd /opt/paperless
docker compose pull
docker compose up -d

Logs prüfen:

docker compose logs -f

Fazit

Mit dieser Anleitung hast du in wenigen Minuten ein leistungsfähiges, selbst gehostetes DMS am Start – ganz ohne schwerfällige Server oder VMs. Paperless-ngx ist leichtgewichtig, OCR-fähig und perfekt für Homelab oder kleine Unternehmen.