Schlagwortarchiv für: Self-Hosting

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

Debian 12 auf 13 Upgrade im Proxmox LXC Container

Debian 12 auf 13 Upgrade im Proxmox LXC Container (Copy & Paste)

Debian 12 Bookworm auf 13 Trixie upgraden, direkt im LXC Container auf Proxmox. Fertiges Script zum Copy & Paste, plus Backup und Verifikation.

Vorher: Snapshot

Vor jedem Major-Upgrade einen Snapshot des Containers erstellen. Einzige einfache Rückfallebene bei Problemen.

pct snapshot <CTID> pre-debian13-upgrade

Das Upgrade-Script

Im Container als root ausführen:

cat <<EOF >/etc/apt/sources.list
deb http://ftp.debian.org/debian trixie main contrib non-free non-free-firmware
deb http://ftp.debian.org/debian trixie-updates main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
deb http://ftp.debian.org/debian trixie-backports main contrib non-free non-free-firmware
EOF

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get -o Dpkg::Options::="--force-confold" dist-upgrade -y

# Disable services that break in LXC / containers (harmless if not present)
systemctl disable --now systemd-networkd-wait-online.service || true
systemctl disable --now systemd-networkd.service || true
systemctl disable --now ifupdown-wait-online || true

# Install ifupdown2 (better networking stack for LXC/VMs)
apt-get install -y ifupdown2

# Cleanup
apt-get autoremove --purge -y
apt-get clean

reboot

Was das Script macht

  • Sources.list: ersetzt Bookworm-Quellen durch Trixie-Quellen, inklusive Security und Backports.
  • dist-upgrade: zieht alle Pakete auf Trixie, –force-confold behält bestehende Config-Dateien bei Konflikten.
  • Service-Disables: systemd-networkd-wait-online, systemd-networkd und ifupdown-wait-online können im LXC-Kontext beim Boot hängen bleiben, da sie auf Netzwerk-Hardware warten, die im Container nicht existiert. Deaktivieren verhindert das. || true sorgt dafür, dass das Script nicht abbricht, falls ein Dienst gar nicht installiert ist.
  • ifupdown2: modernerer Networking-Stack, funktioniert zuverlässiger in LXC/VM-Umgebungen als das klassische ifupdown.
  • Cleanup: entfernt nicht mehr benötigte Pakete und den apt-Cache.
  • Reboot: notwendig, damit Kernel-Userspace-Tools, systemd und Netzwerkstack sauber auf Trixie laufen.

Danach: Verifikation

cat /etc/debian_version
lsb_release -a
apt list --upgradable
ip a
systemctl --failed
  • debian_version sollte 13.x zeigen.
  • apt list –upgradable sollte leer sein.
  • ip a prüft, ob die Netzwerkschnittstelle nach dem Reboot korrekt hochgekommen ist.
  • systemctl –failed zeigt fehlgeschlagene Dienste nach dem Upgrade.

Bekannte Stolperfallen

  • Container-Config auf Proxmox-Host prüfen: sehr alte LXC-Templates können mit Trixie inkompatible Cgroup- oder AppArmor-Profile mitbringen.
  • Bei gepinnten Paket-Repos (Docker, PostgreSQL, etc.) müssen deren eigene sources.list-Einträge separat auf trixie umgestellt werden, das Script deckt nur die Debian-Basisquellen ab.
  • Nach dem Upgrade Dienste einzeln prüfen, die auf spezifische Paketversionen angewiesen sind (z. B. PHP, Python, Datenbanken).

Rollback

Bei Problemen: Container stoppen, Snapshot aus dem ersten Schritt zurückspielen.

pct rollback <CTID> pre-debian13-upgrade

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.

Immich: Deine private Cloud für Fotos und Videos – Step-by-Step Anleitung zur Selbstinstallation

, ,

Warum Immich?

Immich ist eine quelloffene, selbstgehostete Lösung zur Verwaltung von Fotos und Videos. Sie bietet Funktionen wie automatische Uploads von Mobilgeräten, Gesichtserkennung und eine moderne Benutzeroberfläche – ähnlich wie Google Fotos, aber mit vollständiger Kontrolle über deine Daten. Ideal für alle, die Wert auf Datenschutz und Unabhängigkeit von großen Cloud-Anbietern legen.

✅ Voraussetzungen

Bevor du mit der Installation beginnst, stelle sicher, dass dein System folgende Anforderungen erfüllt:

  • Betriebssystem: Aktuelles Linux-System (z. B. Ubuntu, Debian)

  • RAM: Mindestens 4 GB (6 GB oder mehr empfohlen)

  • CPU: Mindestens 2 Kerne (4 Kerne oder mehr empfohlen)

  • Docker: Installiert und funktionsfähig

️ Schritt 1: Docker und Docker Compose installieren

Installiere Docker und Docker Compose, um Immich in Containern auszuführen:

bash
sudo apt update
sudo apt install docker.io docker-compose -y
sudo systemctl enable docker
sudo systemctl start docker

Schritt 2: Projektverzeichnis erstellen

Erstelle ein Verzeichnis für Immich und wechsle hinein:

bash
mkdir ~/immich
cd ~/immich

Schritt 3: Docker-Compose-Datei herunterladen

Lade die offizielle docker-compose.yml-Datei von Immich herunter:

bash
curl -L https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml -o docker-compose.yml

⚙️ Schritt 4: Umgebungsvariablen konfigurieren

Erstelle eine .env-Datei mit den erforderlichen Umgebungsvariablen, z. B.:

env
UPLOAD_LOCATION=/pfad/zu/deinen/fotos
DB_PASSWORD=dein_sicheres_passwort

Passe den Pfad und das Passwort entsprechend an.

Schritt 5: Immich starten

Starte Immich mit Docker Compose:

bash
docker-compose up -d

Die Dienste werden im Hintergrund gestartet.

Schritt 6: Weboberfläche aufrufen

Öffne deinen Browser und gehe zu:

cpp

http://<deine-server-ip>:2283

Registriere dich als Administrator und beginne mit der Einrichtung.

Schritt 7: Mobile App installieren

Lade die Immich-App für dein Mobilgerät herunter:

Melde dich mit der Serveradresse und deinen Zugangsdaten an, um automatische Uploads zu aktivieren.

Optional: Reverse Proxy einrichten

Für den Zugriff über eine eigene Domain und HTTPS kannst du einen Reverse Proxy wie Nginx oder Traefik konfigurieren. Dies ermöglicht eine sichere und benutzerfreundliche Verbindung zu deinem Immich-Server.

Backup und Sicherheit

Denke daran, regelmäßige Backups deiner Medien und der Immich-Datenbank zu erstellen. Nutze Tools wie rsync oder borgbackup für die Datensicherung.

✅ Fazit

Mit Immich erhältst du eine leistungsstarke, selbstgehostete Lösung zur Verwaltung deiner Fotos und Videos. Du behältst die volle Kontrolle über deine Daten und profitierst von Funktionen, die sonst nur große Cloud-Anbieter bieten. Die Einrichtung ist dank Docker unkompliziert und flexibel anpassbar.

Für weitere Informationen und detaillierte Anleitungen besuche die offizielle Immich-Dokumentation:

Immich Quick Start Guide