iac-immich

Immich sichert Fotos und Videos vom Handy (Apps für Android und iOS), zeigt sie in einer Zeitleiste und auf einer Karte und findet sie über Gesichter, Orte und eine Freitextsuche („Hund am Strand“). Nativ auf Debian 13 als LXC oder VM auf Proxmox VE. Teil von iac.

Installation (auf der Proxmox-Node)

bash -c "$(curl -fsSL https://iac.heyer.systems/immich/ct.sh)"   # LXC
bash -c "$(curl -fsSL https://iac.heyer.systems/immich/vm.sh)"   # VM

Ohne Dialog: IAC_NONINTERACTIVE=1 und var_*-Variablen – am einfachsten mit dem Generator auf https://iac.heyer.systems/apps/immich/.

Standard: 4 CPUs, 6 GiB RAM, 32 GiB Platte. Die Fotos brauchen meist mehr Platz – dafür eine eigene Platte einhängen (siehe Einstellungen). Die Installation baut Immich aus dem Quellcode und dauert je nach CPU 10–20 Minuten.

Anmeldung und Zugriff

• Weboberfläche, API und Apps: http://<ip>:2283/ – Port 2283 ist aus allen Netzen erreichbar (Immich hat ein eigenes Login). Für HTTPS einen Reverse Proxy davorsetzen; die Apps brauchen für den Zugriff von unterwegs eine öffentliche Adresse.
• Login: admin@example.com, Passwort im Gast: grep immich_admin_password /etc/iac/settings.env. iac legt diesen Administrator nur an, solange es noch keinen gibt; ein später geändertes Passwort bleibt. E-Mail-Adresse und Passwort unter Kontoeinstellungen ändern.
• Weitere Benutzer legt der Administrator unter Administration → Benutzer an. Eine Einrichtung im Browser („erster Besucher wird Admin“) gibt es nicht.
• Machine Learning (Gesichter, Suche, Texterkennung) läuft nur auf 127.0.0.1:3003. Die Modelle lädt es beim ersten Gebrauch von Hugging Face (rund 1 GiB nach /var/lib/immich/ml-cache).

Einstellungen

• immich_media_location (in /etc/iac/settings.env, danach update): Verzeichnis für Fotos, Videos, Vorschaubilder und Datenbank-Backups von Immich, Standard /var/lib/immich/library. Für eine eigene Platte diese in Proxmox dort einhängen (z. B. pct set <id> -mp0 <storage>:<GiB>,mp=/var/lib/immich/library) oder den Pfad des Einhängepunkts eintragen. Ändert sich der Pfad bei bestehenden Fotos, schreibt Immich beim Start die Pfade in der Datenbank um – die Dateien vorher selbst dorthin verschieben.
• /etc/immich/immich.env gehört iac und wird bei jedem update neu geschrieben. Eigene Einstellungen (siehe Umgebungsvariablen) gehören nach /etc/immich/immich.local.env – gleiches Format NAME=wert, wird danach gelesen und gewinnt. Danach systemctl restart immich-server immich-ml.
• Fast alles Weitere (SMTP, OAuth, Speichervorlagen, Transkodierung, Modelle) stellt man in der Weboberfläche unter Administration → Einstellungen ein. Mails: mit dem Modul mail-relay dort SMTP-Server 127.0.0.1, Port 25, ohne Anmeldung.

Wo was liegt

Pfad	Inhalt
/var/lib/immich/library	Medien (IMMICH_MEDIA_LOCATION): Originale, Vorschaubilder, transkodierte Videos, Profilbilder, Datenbank-Backups von Immich (backups/)
/var/lib/immich/ml-cache	Modelle des Machine Learning
PostgreSQL (Modul)	Datenbank immich mit VectorChord, Benutzer immich
/etc/immich/immich.env	Konfiguration von iac
/etc/immich/immich.local.env	eigene Einstellungen (optional)
/opt/immich/current	aktives Release: Server, Weboberfläche, CLI, Node.js, libvips, Python-Umgebung des Machine Learning, Geodaten
/usr/local/sbin/immich-admin	Verwaltung, z. B. immich-admin reset-admin-password, immich-admin list-users
/usr/local/bin/immich	CLI von Immich, z. B. um einen vorhandenen Ordner hochzuladen

Die Dienste immich-server und immich-ml laufen als eigener Benutzer immich mit systemd-Härtung und dürfen nur /var/lib/immich und das Medienverzeichnis beschreiben. Die Datenbankrolle immich ist Superuser – Immich legt seine Erweiterungen selbst an und aktualisiert sie, und seine Datenbank-Backups nutzen pg_dumpall (wie im offiziellen Setup).

Herkunft und Update

Immich veröffentlicht keine Release-Archive oder Checksummen. iac klont deshalb das Git-Tag v<version> und prüft, dass es auf den Commit zeigt, den die GitHub-API meldet. Alles andere nimmt iac so, wie das Release es festlegt:

• Node.js in der Version aus mise.toml (Checksumme von nodejs.org), pnpm aus packageManager, die JavaScript-Pakete mit Hashes aus pnpm-lock.yaml, extism-js und binaryen für das Kern-Plugin mit Checksummen aus mise.lock
• uv in der Version aus dem Dockerfile des Machine Learning, die Python-Pakete mit Hashes aus uv.lock, Python 3.13 von Debian
• aus den Basis-Images des Releases (immich-app/base-images, Tag ebenfalls gegen die GitHub-API geprüft): libvips (Commit und Patches), jellyfin-ffmpeg (Checksumme aus den Basis-Images), VectorChord (SHA-256 von GitHub für das Release-Asset)

Anders als das offizielle Image baut iac nur libvips selbst (Immich braucht ≥ 8.18, Debian 13 hat 8.16) – gegen libheif, libde265, libjxl, LibRaw und ImageMagick aus Debian, die so Sicherheitsupdates von Debian bekommen. HEIC, AVIF, JPEG XL und RAW funktionieren damit. Die Geodaten für die Ortszuordnung (geonames.org, Natural Earth) haben keine Checksummen; iac lädt sie wie das offizielle Image nur über HTTPS, einmal pro Release.

update

update baut die neueste Version derselben Major-Version ("major_lock": true) unter /var/tmp (rund 6 GiB, danach wieder frei) – das dauert einige Minuten –, schaltet /opt/immich/current um, startet neu (Immich migriert die Datenbank beim Start) und löscht das vorige Release. Eine neue Major-Version wird nur angezeigt; vor dem Wechsel die Release Notes lesen.

Hardwarebeschleunigung (Transkodierung per GPU, OpenVINO/CUDA für das Machine Learning) richtet iac nicht ein; die Dienste sehen keine Geräte (PrivateDevices=true).

Bestehende Installation übernehmen

Installationen des Proxmox-VE-Community-Scripts (ct/immich.sh: /opt/immich, PostgreSQL 16 aus dem PGDG-Repository) übernimmt adopt.sh im bestehenden Gast – die Datenbank zieht dabei per Dump nach PostgreSQL 17 von Debian. Ablauf und andere Wege: docs/MIGRATION.md.

bash -c "$(curl -fsSL https://iac.heyer.systems/immich/adopt.sh)"

Selbsttest (im Gast)

bash /var/lib/iac/src/core/bin/iac-smoke