Schlagwortarchiv für: Docker Compose

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-AI in Proxmox als LXC-Container installieren – Step-by-Step Anleitung

, ,


Paperless-AI ist ein Dokumentenmanagementsystem mit integrierter KI – ideal für alle, die Dokumente nicht nur digitalisieren, sondern auch intelligent auswerten lassen wollen. In dieser Anleitung zeige ich dir, wie du Paperless-AI sauber und einfach in einem Proxmox LXC-Container installierst.

Voraussetzungen

  • Proxmox VE 7 oder 8

  • Ubuntu 22.04 LXC-Container

  • Mind. 2–4 GB RAM

  • 1–2 CPU-Kerne

  • Docker & Docker Compose

  • OpenAI API Key (optional, für KI-Funktionen)

Schritt 1: LXC-Container anlegen

Erstelle im Proxmox Webinterface einen neuen Container:

  • Template: ubuntu-22.04-standard

  • Hostname: paperlessai

  • RAM: mind. 2–4 GB

  • CPU: 1–2 Kerne

  • Festplatte: 10–20 GB (je nach Dokumentenmenge)

  • Netzwerk: statische IP oder DHCP

Wichtig:

Aktiviere unter “Options” die Features nesting und fuse.

Schritt 2: Container vorbereiten

Per Shell oder SSH:

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

Schritt 3: Paperless-AI klonen & konfigurieren

git clone https://github.com/paperless-ai/paperless-ai.git /opt/paperless-ai
cd /opt/paperless-ai

Kopiere die Beispiel-Konfiguration:

cp .env.template .env

Bearbeite .env und trage z. B. deinen OpenAI API-Key ein:

OPENAI_API_KEY=sk-...
PAPERLESS_TIME_ZONE=Europe/Berlin

Optional kannst du auch HuggingFace oder andere Modelle einbinden.

Schritt 4: Container starten

docker compose up -d

Der Start dauert beim ersten Mal ein paar Minuten.

Danach erreichst du Paperless-AI über:

http://<IP_DES_CONTAINERS>:8000

Erstkonfiguration

Erster Benutzer:

docker compose exec web python3 manage.py createsuperuser

Dann einloggen und das Dashboard erkunden.

Dokumente hochladen

Dokumente kannst du via Web-UI oder in den Ordner /opt/paperless-ai/data/consume/ hochladen:

scp rechnung.pdf root@<IP>:/opt/paperless-ai/data/consume/

Die Dokumente werden automatisch verarbeitet und mit Hilfe der KI ausgewertet (z. B. Felder wie Rechnungsnummer, Absender, Betrag usw.).

Updates & Wartung

Update auf neueste Version:

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

Logs ansehen:

docker compose logs -f

Fazit

Mit Paperless-AI kombinierst du OCR und KI-basierte Analyse in einem System – ideal für Selbstständige, IT-affine Nutzer oder kleine Büros. In Proxmox als LXC läuft es besonders ressourcenschonend und stabil. Damit erweitert man den Paperless-NGX um AI Funktionen mit OpenAI oder Local mit Ollama einfach nutzen.

Homepage / Download Entwickler: https://github.com/clusterzx/paperless-ai

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.