PKR-Lab

300c0 - Immich

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300c0-immich.md

Immich

Cluster: PROD · Ordner argocd/apps/prod/immich/ · URL https://immich.prod.homeserver und https://immich-prod.pke-lab.de. kubectl-Befehle in diesem Doc gelten für den PROD-Cluster (Zugriff je Cluster).

Immich ist ein selbst gehostetes Foto-/Video-Backup
(Google-Photos-Ersatz) mit automatischem Handy-Upload, Gesichtserkennung
und Timeline-Ansicht. Die Deployment-Konfiguration liegt unter
argocd/apps/prod/immich/, der zugehörige NAS-Storage (StorageClass
immich-nas) unter argocd/apps/prod/immich-storage/.


Übersicht

Komponente Technologie Namespace
immich-server ghcr.io/immich-app/immich-server:v3.1.0 immich
immich-machine-learning ghcr.io/immich-app/immich-machine-learning:v3.1.0 (Gesichtserkennung, CLIP-Suche, reine CPU) immich
Datenbank PostgreSQL 14 + VectorChord (ghcr.io/immich-app/postgres) immich
Job-Queue Valkey (Redis-kompatibel) immich
Ingress Traefik immich
Secrets SealedSecrets immich
Persistenz StorageClass immich-nas (dedizierter NFS-Export) —

Warum keine PostgreSQL-Standard-Images wie bei Wiki.js/Nextcloud?
Immichs Ähnlichkeitssuche (Gesichter, "Suche nach Motiv") basiert auf
Vektor-Embeddings, die eine Postgres-Extension (VectorChord, vormals
pgvecto.rs) brauchen. Das offizielle ghcr.io/immich-app/postgres-Image
bringt diese Extension bereits vorinstalliert mit — ein Standard-
postgres-Image reicht hier nicht.


Dedizierter Storage: immich-nas statt nas

Anders als die übrigen Apps in diesem Repo liegt Immichs kompletter
Storage (Fotobibliothek, Postgres-Daten, ML-Modell-Cache) nicht auf
der generischen nas-StorageClass (/volume1/k8s-storage), sondern auf
einer eigenen StorageClass immich-nas, die auf einen zweiten,
unabhängigen NFS-Export zeigt: /volume2/immich-storage.

┌─────────────── UGREEN NAS ───────────────┐
│  /volume1/k8s-storage   → StorageClass "nas"        (Nextcloud, Wiki.js, …)
│  /volume2/immich-storage → StorageClass "immich-nas" (nur Immich)
└───────────────────────────────────────────┘

Begründung: Die Fotobibliothek wächst unabhängig und potenziell
deutlich schneller als der restliche Cluster-Storage — mit einem eigenen
Export lassen sich Kapazität, Backup-Priorität und ggf. später ein
eigenes RAID-Volume unabhängig vom übrigen Cluster-Storage planen, ohne
dass ein einzelner großer Fotobestand den gemeinsamen k8s-storage-Export
volllaufen lässt.

argocd/apps/tech/immich-storage/ deployt dafür einen zweiten
nfs-subdir-external-provisioner (eigener PROVISIONER_NAME, eigene
RBAC-Ressourcen, eigener Namespace immich-storage) — technisch identisch
zum bestehenden nas-storage-Setup aus
capulus-core/2-betrieb-hardware/20000-nas-storage.md, nur auf einen anderen Export
gerichtet.


Voraussetzungen


Schritt 1 — NFS-Export für Immich einrichten (UGOS, manuell)

Analog zu
capulus-core/2-betrieb-hardware/20000-nas-storage.md → NFS-Export in UGOS einrichten,
diesmal auf volume2:

  1. Auf volume2 eine neue Freigabe immich-storage anlegen.
  2. NFS-Regel-Eintrag für diese Freigabe:
    • Erlaubte Hosts: 192.168.178.0/24
    • Berechtigung: Lese-/Schreibzugriff
    • Squash: no_root_squash
  3. Exportpfad prüfen — falls abweichend von /volume2/immich-storage,
    sowohl argocd/apps/tech/immich-storage/deployment.yaml
    (NFS_SERVER/NFS_PATH sowie den nfs-Volume-Block) als auch
    argocd/apps/tech/immich-storage/storageclass.yaml-Kommentar entsprechend
    anpassen.
  4. Verbindung testen:
    sudo mount -t nfs 192.168.178.97:/volume2/immich-storage /mnt
    touch /mnt/test && ls /mnt && sudo umount /mnt
    

Danach argocd/apps/tech/immich-storage/ deployen lassen (Root-ApplicationSet
erkennt den neuen Ordner automatisch) und verifizieren:

kubectl get storageclass immich-nas
kubectl -n immich-storage get pods

Schritt 2 — Secret versiegeln

DB_PASS=$(openssl rand -base64 32 | tr -d '=+/' | head -c 32)
echo -n "$DB_PASS" | kubeseal --raw \
  --namespace immich --name immich-secrets \
  --controller-namespace sealed-secrets \
  --controller-name sealed-secrets-controller

Ausgabe in argocd/apps/prod/immich/values.yaml eintragen:

secrets:
  enabled: true
  name: immich-secrets
  encryptedDbPassword: "<Ausgabe von kubeseal>"

Schritt 3 — Deployment via ArgoCD

kubectl get pods -n immich -w

Erwartete Reihenfolge: immich-postgresql-* + immich-redis-* zuerst,
dann immich-server-* und immich-machine-learning-*. Der
ML-Container lädt beim ersten Start seine Modelle herunter (landet im
model-cache-PVC) — das kann je nach Verbindung ein paar Minuten dauern,
danach ist der Cache persistent und Neustarts sind schnell.

DNS: Immich läuft im PROD-Cluster; immich.prod.homeserver steht in dnsmasq_prod_vm_hosts (capulus-ansible/group_vars/all.yml) und zeigt auf die PROD-VM (.99).

Machine-Learning-Verbindung: immich-server erwartet den
ML-Dienst standardmäßig unter http://immich-machine-learning:3003
(Immichs eingebauter Default). Der Service-Name in diesem Chart ist
exakt immich-machine-learning (im selben Namespace) — das passt ohne
weitere Konfiguration. Falls in Administration → Einstellungen →
Machine Learning → URL
trotzdem ein Fehler auftaucht, dort explizit
http://immich-machine-learning.immich.svc.cluster.local:3003
eintragen.


Schritt 4 — Erstlogin und Handy-App

  1. https://immich.prod.homeserver öffnen → erster Aufruf legt den
    Admin-Account an (kein separates Admin-Passwort in values.yaml nötig
    — Immich fragt das im Browser ab)
  2. Handy-App (iOS/Android, "Immich"): Server-URL
    https://immich.pke-lab.de eintragen (siehe
    Externe Erreichbarkeit
    unten) — nötig, damit Auto-Backup auch unterwegs (nicht im
    LAN/Tailnet) funktioniert, analog zu Vaultwarden.
  3. In der App unter Backup die zu sichernden Alben/den gesamten
    Kamera-Roll auswählen.

Nutzer-Inventar: Wer einen Account hat und welche Library/welches
Album ihm zugeordnet ist, wird zusätzlich (verschlüsselt, außerhalb der
App-DB) in capulus-ansible/group_vars/user_inventory_vault.yml festgehalten —
make user-inventory-edit zum Bearbeiten, siehe
capulus-core/4-planung/40080-multi-cluster-entw-prod-tech.md → Baustein 7
für den Zweck (Dokumentation, kein Ersatz für die eigentliche DB).


Externe Bibliothek: Bestehende Fotoordner importieren (z. B. OneDrive-Export)

Für Fotos, die schon als fertige Ordnerstruktur vorliegen (z. B. ein
Massen-Export aus OneDrive) und nicht einzeln über Handy-App/Web-Upload
hochgeladen werden sollen, unterstützt Immich sogenannte
External Libraries: Ordner
werden read-only in den immich-server-Container gemountet und nur
eingelesen/indexiert — die Dateien bleiben unverändert auf dem NAS liegen,
es entsteht kein Duplikat in der library-PVC.

Wichtig: Dateien einfach in die library-PVC (/data, siehe
Übersicht oben) kopieren funktioniert nicht — dieser
Pfad wird ausschließlich von Immich selbst verwaltet (UUID-Struktur für
Uploads/Thumbnails), es gibt keinen automatischen Scan dieses Ordners.

Schritt A — Unterordner auf dem bestehenden Immich-NFS-Export anlegen

Kein neuer NFS-Export nötig — die Firewall-/Host-Regel für
/volume2/immich-storage (siehe Schritt 1
oben) erlaubt bereits Lese-/Schreibzugriff für 192.168.178.0/24. Einfach
einen Unterordner anlegen und die OneDrive-Ordner dort hinein
kopieren/synchronisieren, z. B.:

/volume2/immich-storage/external/onedrive/<deine Ordnerstruktur>

Schritt B — Mount in argocd/apps/prod/immich/values.yaml aktivieren

server:
  externalLibrary:
    enabled: true
    mountPath: /mnt/external
    nfs:
      server: "192.168.178.97"
      path: "/volume2/immich-storage/external"
      readOnly: true

Weitere, unabhängige Ordner lassen sich über extraMounts einbinden:

    extraMounts:
      - name: onedrive-fotos
        mountPath: /mnt/external/onedrive
        server: "192.168.178.97"
        path: "/volume2/immich-storage/external/onedrive"
        readOnly: true

Nach dem ArgoCD-Sync verifizieren:

kubectl -n immich exec deploy/immich-server -- ls /mnt/external

Schritt C — Library in der Immich-UI anlegen

Administration → Libraries → Create Library → External Library →
Import-Pfad exakt auf den gemounteten Container-Pfad setzen (z. B.
/mnt/external oder /mnt/external/onedrive bei extraMounts). Danach
Scan Library anstoßen (manuell oder per Intervall in den
Library-Einstellungen) — Immich indexiert dann rekursiv alle Unterordner.

Read-only reicht aus: Immich muss die Originaldateien nur lesen, es
schreibt keine Metadaten in den externen Ordner zurück.


Externe Erreichbarkeit (Cloudflare Tunnel)

immich.pke-lab.de ist bereits in
argocd/apps/tech/cloudflared/values.yaml eingetragen (zeigt auf
immich-server.immich.svc.cluster.local:80). Das ist hier kein
optionales Extra
, sondern für den Kernanwendungsfall
(automatisches Foto-Backup vom Handy) notwendig — ohne Erreichbarkeit von
unterwegs würde die App nur zuhause im WLAN synchronisieren.


Postgres-Backup

Ergänzend zum nächtlichen Datei-Level-restic-Backup von immich-nas
(capulus-core/2-betrieb-hardware/20010-nas-backup.md —
das ist kein transaktions-konsistenter Snapshot, siehe dort
"Hinweis: Konsistenz laufender Datenbanken") läuft täglich um 01:50 Uhr
ein eigener pg_dump-CronJob (immich-postgres-backup, Muster wie
das frühere Authentik-Backup), der einen
transaktions-konsistenten Dump auf eine separate NAS-gestützte PVC
(immich-postgres-backup, StorageClass immich-nas) schreibt — die
letzten 7 Dumps bleiben erhalten, ältere werden automatisch entfernt.

Bekannte Falle, die genau diesen CronJob betraf (behoben
2026-09-18):
Frisch gestartete Pods können in diesem Cluster die
ersten paar Sekunden nach dem Start noch keine Cross-Pod-Service-
Verbindung aufbauen (Netzwerk-Startup-Race) — ein pg_dump, der sofort
beim Container-Start verbindet, bekommt Connection refused und
pg_dump -f hat die Ziel-Datei da schon (leer) angelegt, was ohne
genaues Hinsehen wie ein erfolgreicher, aber leerer Dump aussieht.
Der CronJob wartet deshalb per pg_isready-Schleife (bis zu 30s) auf
Erreichbarkeit, bevor er pg_dump startet — siehe
capulus-core/4-planung/40080-multi-cluster-entw-prod-tech.md
für den vollen Befund (derselbe Bug betraf auch Authentiks Backup-CronJob).

Manueller Dump/Restore (z. B. vor einer riskanten Änderung, siehe
auch den Major-Upgrade-Ablauf unten):

kubectl -n immich exec deploy/immich-postgresql -- \
  pg_dump -U immich -Fc immich > immich-$(date +%F).dump

kubectl -n immich cp immich-*.dump immich-postgresql-<pod>:/tmp/restore.dump
kubectl -n immich exec deploy/immich-postgresql -- \
  pg_restore -U immich -d immich /tmp/restore.dump

Datenbank-Major-Upgrade (Postgres 14 → 16)

Gleiches Grundprinzip wie bei Nextcloud
und Wiki.js — mit
zwei Immich-spezifischen Besonderheiten:

Ablauf:

  1. Dump (ergänzend zum nächtlichen restic-Backup unter der separaten
    immich-nas-StorageClass, siehe
    capulus-core/2-betrieb-hardware/20010-nas-backup.md):
    kubectl -n immich exec deploy/immich-postgresql -- \
      pg_dump -U immich -Fc immich > immich-pg14-$(date +%F).dump
    
  2. Beide Consumer stoppen:
    kubectl -n immich scale deploy/immich-server immich-machine-learning --replicas=0
    
  3. In der Chart-Vorlage:
    • values.yaml: postgresql.image.tag auf den neuen Postgres-16-Tag
      mit passendem VectorChord-Suffix setzen (siehe Hinweis oben).
    • templates/postgres-deployment.yaml: PGDATA von
      /var/lib/postgresql/data/pgdata_fixed auf
      /var/lib/postgresql/data/pgdata_fixed_pg16 ändern — gleicher Trick
      wie bei Wiki.js, runAsUser/runAsGroup: 1000/10 unverändert lassen.
    • Committen/pushen, ArgoCD syncen lassen.
  4. Dump zurückspielen — pg_restore legt die VectorChord-Extension dabei
    automatisch mit an (im Dump als CREATE EXTENSION-Statement enthalten,
    die Extension selbst ist im Ziel-Image bereits vorhanden):
    kubectl -n immich cp immich-pg14-*.dump immich-postgresql-<pod>:/tmp/restore.dump
    kubectl -n immich exec deploy/immich-postgresql -- \
      pg_restore -U immich -d immich /tmp/restore.dump
    
  5. Beide Consumer wieder hochskalieren, App öffnen, Timeline + Gesichts-/
    Ähnlichkeitssuche stichprobenartig prüfen (letzteres hängt direkt an
    VectorChord — ein guter Indikator, dass die Extension sauber
    mitgewandert ist).
  6. Rollback: Schritt 3 revertieren, alter pgdata_fixed-Ordner bleibt
    unangetastet auf derselben PVC.
  7. Nach störungsfreier Testphase alten pgdata_fixed-Ordner aufräumen.

Troubleshooting

immich-postgresql/immich-server-PVC bleibt Pending

kubectl describe pvc -n immich <pvc-name>
kubectl -n immich-storage get pods
kubectl -n immich-storage logs deploy/immich-nfs-subdir-external-provisioner

Meist: NFS-Export /volume2/immich-storage ist vom Node aus nicht
erreichbar, oder der immich-storage-Provisioner-Pod läuft nicht. Details
analog zu capulus-core/2-betrieb-hardware/20000-nas-storage.md → Fehlerbehebung.

Gesichtserkennung/Suche liefert keine Ergebnisse

kubectl logs -n immich deploy/immich-machine-learning

Prüfen, ob der ML-Container die Modelle erfolgreich heruntergeladen hat
(erster Start braucht Internetzugang) und ob Administration →
Einstellungen → Machine Learning
in der Immich-UI aktiviert ist.

SealedSecret wird nicht entschlüsselt

kubectl describe sealedsecret -n immich immich-secrets

Ressourcenverbrauch (Richtwerte Home Lab)

Komponente CPU Request RAM Request RAM Limit Storage
immich-server 250m 512Mi 4Gi 500Gi Bibliothek (immich-nas)
immich-machine-learning 500m 1Gi 4Gi 10Gi Modell-Cache (immich-nas)
PostgreSQL 200m 512Mi 2Gi 20Gi (immich-nas)
Valkey/Redis 25m 64Mi 256Mi —
Gesamt (1 Replica je Komponente) ~975m ~2,1Gi ~10,25Gi 530Gi auf immich-nas
Worst Case (volle Autoskalierung, siehe unten) — — ~22,25Gi —

server.persistence.library.size NICHT nachträglich erhöhen: die
immich-nas-StorageClass hat allowVolumeExpansion: false (siehe
argocd/apps/tech/immich-storage/storageclass.yaml), der
nfs-subdir-external-provisioner unterstützt kein PVC-Resize. Ein
höherer Wert bleibt dauerhaft OutOfSync in ArgoCD (Fehler
"only dynamically provisioned pvc can be resized ..."), ohne dass sich
am tatsächlich belegten NAS-Speicher etwas ändert — die Größe ist hier
reine Kubernetes-Quota, aber eben einmalig bei PVC-Erstellung fix. Für
mehr Platz die PVC löschen (Daten bleiben dank reclaimPolicy: Retain
auf dem NAS erhalten) und mit neuem size-Wert neu anlegen lassen.
So auch bei Nextcloud (nas-StorageClass, dieselbe Einschränkung).

Das RAM-Limit für immich-server wurde am 2026-07-27 bewusst von 2Gi auf
4Gi angehoben (Absturz bei großen Uploads, siehe
../b-kubernetes-gitops/b0040-hpa-autoscaling.md) —
NICHT wieder absenken, ohne die Ursache dieser Änderung erneut zu prüfen.
Da der Worst-Case-Wert (volle Autoskalierung aller vier Komponenten
gleichzeitig auf demselben Node, siehe podAffinity unten) einen
erheblichen Teil des Homeserver-RAM beanspruchen kann, greift stattdessen
der Kubelet-RAM-Schutz:
Der Kubelet evakuiert/killt einzelne Pods, bevor die Gesamtlast den Node
gefährdet.


Autoskalierung (HPA)

immich-server (1–3 Replicas) und immich-machine-learning (1–2
Replicas) skalieren per HPA auf CPU 75% / RAM 80% hoch — das hilft bei
vielen gleichzeitigen Uploads, nicht bei einem einzelnen Foto/Video,
das für sich allein schon mehr RAM braucht als resources.limits
erlaubt (dafür ggf. das Limit selbst erhöhen). Da library- und
model-cache-PVC ReadWriteOnce sind, erzwingt eine podAffinity im
jeweiligen Deployment, dass alle Replicas auf demselben Node laufen.
Details und Schwellenwerte für alle Apps: ../b-kubernetes-gitops/b0040-hpa-autoscaling.md.