Immich Docker Compose einrichten: Fotos selbst hosten

Mit Immich Docker Compose betreibst du eine eigene Fotoverwaltung mit Weboberfläche und mobilen Uploads auf einem Linux-Server. Dieser Leitfaden richtet Speicher, Datenbank und Container so ein, dass du den Dienst prüfen und später vollständig sichern kannst. Docker Compose ist laut Immich die empfohlene Produktionsmethode.

Stand: 20.10.2026

Auf einen Blick

• Plane Foto-Speicher und PostgreSQL getrennt.
• Nutze den aktuellen Release-Compose-Stack, nicht eine Datei aus dem Git-Branch main.
• Setze einen eigenen Datenbankwert und eine passende Zeitzone.
• Prüfe Containerstatus und Log-Ausgabe vor dem ersten Upload.
• Sichere immer Datenbank und UPLOAD_LOCATION.

1. Die Ausgangslage und das Ziel

Immich ist sinnvoll, wenn Fotos und Videos auf eigener Infrastruktur liegen sollen, ohne auf eine bloße Ordnerfreigabe reduziert zu sein. Die Anwendung verwaltet Uploads, Vorschauen, Transkodierungen und Metadaten. Deshalb besteht ein funktionierendes Immich Docker Compose-Projekt aus mehr als einem einzelnen Webcontainer.

Das Ziel ist eine nachvollziehbare Installation auf einem 64-Bit-Linux-System mit Docker Engine und Compose-Plugin. Die offizielle Anforderung nennt mindestens zwei CPU-Kerne und 6 GB RAM; für einen flüssigeren Betrieb, insbesondere beim Upload, werden 8 GB empfohlen. Rechne außerdem Speicher für Vorschauen und transkodierte Videos ein: Laut Anforderungen kann die Fotobibliothek dadurch durchschnittlich um 10 bis 20 Prozent wachsen.

Docker auf einem Raspberry Pi folgt anderen Ressourcenregeln; für den Einstieg hilft der vorhandene Artikel Docker auf dem Raspberry Pi installieren. Für Immich selbst ist amd64 oder arm64 vorgesehen. In einer virtualisierten Umgebung empfiehlt die Immich-Dokumentation eine vollständige VM statt Docker in einem LXC.

Teil 1 – Voraussetzungen und Architektur

2. Speicher vor dem Download festlegen

Lege zuerst fest, wo Fotos liegen und wo PostgreSQL schreibt. UPLOAD_LOCATION enthält nicht nur Originale, sondern auch generierte Inhalte und Datenbankdumps. DB_DATA_LOCATION ist dagegen der Datenbankpfad. Beide Werte stehen in .env, damit du die mitgelieferte Compose-Datei nicht verändern musst.

Die Datenbank gehört auf ein lokales, Unix-kompatibles Dateisystem und idealerweise auf eine SSD. Netzwerkfreigaben werden für PostgreSQL nicht unterstützt. Das ist keine akademische Einschränkung: Immich bezeichnet gute Performance und eine stabile Datenbankverbindung ausdrücklich als kritisch. Ein ZFS-, ext4-, Btrfs- oder XFS-Dateisystem passt, sofern Eigentümer und Rechte unterstützt werden.

Die Architektur macht diese Trennung sichtbar.

3. Docker und Compose prüfen

Prüfe vorab, ob Docker Engine und das Compose-Plugin verfügbar sind. Der relevante Aufruf enthält ein Leerzeichen: docker compose. Das ältere docker-compose ist laut Dokumentation abgekündigt und wird von Immich nicht unterstützt. Lies bei einem neuen Docker-Host zusätzlich die Docker-Compose-Grundlagen, damit Volumes und Projektverzeichnisse klar sind.

Dieser Befehl zeigt beide Voraussetzungen.

docker --version
docker compose version

Erfolg erkennst du an einer Docker- und einer Compose-Version; fehlt der zweite Befehl, installiere erst das Plugin nach der Docker-Dokumentation.

Teil 2 – Immich Docker Compose installieren

4. Projektordner und Release-Dateien anlegen

Erstelle einen eigenen Projektordner. Danach lädst du die zwei Release-Dateien, die Immich selbst für die Installation nennt. Verwende nicht die Compose-Datei aus dem Git-Branch main: Das offizielle Repository warnt ausdrücklich, dass sie nicht zum neuesten Release passen muss.

Diese Befehle erzeugen den Ordner und laden die aktuelle Compose-Datei.

mkdir ./immich-app
cd ./immich-app
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

Danach liegt docker-compose.yml im aktuellen Ordner. Die Datei definiert immich-server, Machine Learning, Valkey und PostgreSQL.

Hole als Nächstes die Umgebungsdatei in denselben Ordner.

wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Erfolg bedeutet hier: .env und docker-compose.yml liegen nebeneinander. Ein manueller Download ist ebenfalls möglich, dann muss example.env zu .env umbenannt werden.

5. Die .env bewusst befüllen

Öffne nun .env mit einem Editor. Entscheidend sind die beiden Speicherorte, die Zeitzone und ein eigener Datenbankwert. Die offizielle Beispieldatei erlaubt für DB_PASSWORD ausschließlich A–Z, a–z und 0–9, weil Sonderzeichen oder Leerzeichen bei der Docker-Auswertung Probleme verursachen können.

Dieses Beispiel zeigt die relevanten Werte. Ersetze die Pfade und das Passwort durch deine Werte; der Passwortplatzhalter darf nicht unverändert bleiben.

UPLOAD_LOCATION=/srv/immich/library
DB_DATA_LOCATION=/srv/immich/postgres
TZ=Europe/Vienna
IMMICH_VERSION=v3
DB_PASSWORD=<DEIN_NUR_ALPHANUMERISCHES_PASSWORT>
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Der Erfolg ist eine gespeicherte .env mit existierenden, beschreibbaren lokalen Pfaden. Bewahre die Datei geschützt auf, weil sie das Datenbankpasswort enthält.

6. Warum die Compose-Datei unverändert bleiben sollte

Der offizielle Stack bindet ${UPLOAD_LOCATION} nach /data ein und verwendet ${DB_DATA_LOCATION} für PostgreSQL. Deshalb änderst du Speicherorte über .env, nicht durch eine Zeile im YAML. Das erleichtert spätere Updates erheblich.

Diese Zeilen aus dem bereitgestellten Stack zeigen die beiden Bindings.

volumes:
  - ${UPLOAD_LOCATION}:/data
  - ${DB_DATA_LOCATION}:/var/lib/postgresql/data

Der Erfolg ist konzeptionell: Die Konfiguration bleibt releasefähig, während deine lokalen Pfade in der separaten Umgebungsdatei stehen.

7. Stack starten

Starte das Projekt aus seinem Verzeichnis im Hintergrund. Compose lädt .env automatisch ein und zieht fehlende Images. Danach erreichst du den Server gemäß der offiziellen Datei über Port 2283; die Datenbank wird dagegen nicht als Host-Port veröffentlicht.

Dieser Befehl startet alle Dienste.

docker compose up -d

Erfolg erkennst du daran, dass Compose Container erstellt oder startet und zum Prompt zurückkehrt. Öffne anschließend http://<DEINE-IP>:2283 und lege den ersten Administrationszugang an. Stelle den Port nur dann über einen Reverse Proxy bereit, wenn dessen Weiterleitung und TLS sauber konfiguriert sind; die Grundlagen dazu beschreibt Traefik im Homelab.

Teil 3 – Betrieb, Updates und Backup

8. Erst prüfen, dann Fotos importieren

Prüfe zuerst den Status aller Dienste. Die Compose-Datei enthält Healthchecks für Server, Machine Learning, Valkey und Datenbank. Dadurch trennt der Status einen erfolgreichen Containerstart von einem tatsächlich bereiten Dienst.

Diese Abfrage listet Dienste und ihren Zustand.

docker compose ps

Erwartet werden die Dienste immich-server, immich-machine-learning, redis und database als laufende Container. Valkey antwortet im Healthcheck mit PONG.

Wenn ein Dienst nicht läuft, sind die jüngsten Logs der nächste belegbare Anhaltspunkt.

docker compose logs --tail=100

Erfolg erkennst du an einem laufenden Server ohne fortlaufende Neustarts. Prüfe anschließend die Weboberfläche, bevor mobile Clients große Mengen hochladen.

9. Updates als kontrollierten Vorgang behandeln

Ein Update beginnt mit dem Lesen der Upgrade-Hinweise zur Zielversion. Lade anschließend die aktuelle Release-Compose-Datei und die zugehörige .env-Vorlage nur zum Vergleichen, nicht zum Überschreiben deiner Konfiguration. Die eigene Datei enthält Pfade und Passwort.

Mit diesem Befehl aktualisierst du die Images und erstellst Container neu.

docker compose pull
docker compose up -d

Danach wiederhole docker compose ps und prüfe die Weboberfläche. Allgemeine Sicherheitsregeln für Container, etwa das Aktualisieren von Images, ergänzt der Artikel Docker Security Tipps.

10. Das Backup muss zwei Datenbereiche erfassen

Ein Datenbankdump alleine enthält keine Fotos oder Videos. Umgekehrt reichen Dateien allein nicht, denn Immich speichert Pfade und Benutzermetadaten in PostgreSQL und scannt den Bibliotheksordner nicht automatisch. Die Immich-Dokumentation empfiehlt deshalb eine 3-2-1-Strategie und eine Kopie von Datenbank sowie UPLOAD_LOCATION.

Die Anwendung legt nach Standard täglich um 2:00 Uhr Datenbankbackups an und behält 14 Sicherungen. Diese liegen unter UPLOAD_LOCATION/backups. Sie sind hilfreich, aber kein Ersatz dafür, das gesamte Verzeichnis auf einen separaten Speicher zu sichern. Für ein restic-basiertes Ziel dient Restic Docker Backup als Ergänzung.

Wenn du für ein konsistentes Backup den Server anhalten kannst, fahre ausschließlich den Anwendungsdienst herunter. Dann ändern sich während der Sicherung keine Assets.

docker compose stop immich-server

Erfolg erkennst du daran, dass immich-server gestoppt ist, während Datenbank und Dateien für die Sicherung zugänglich bleiben. Danach sichere Datenbank und Dateibaum mit deinem Backup-Werkzeug und starte den Server wieder.

Dieser Befehl nimmt den Dienst wieder in Betrieb.

docker compose start immich-server

Falls ein Anhalten nicht möglich ist, schreibt die Dokumentation eine klare Reihenfolge vor: zuerst Datenbank, danach Dateisystem. So können höchstens zusätzliche Dateien ohne Datenbankeintrag entstehen; die umgekehrte Reihenfolge könnte Datenbankeinträge auf fehlende Dateien verweisen lassen.

Die wichtigsten Stolperfallen

Altes docker-compose statt docker compose

Symptom: Die Datei wird als ungültig gemeldet, etwa wegen des Felds name. Ursache: Compose V1 ist abgekündigt. Lösung: Installiere Docker mit Compose-Plugin und nutze docker compose.

Datenbank auf einem Netzwerk-Share

Symptom: Instabile Datenbank oder fehlende Unterstützung. Ursache: Netzwerkfreigaben sind für DB_DATA_LOCATION nicht unterstützt. Lösung: Lege PostgreSQL auf lokaler SSD ab und sichere sie anschließend extern.

Zu wenig Arbeitsspeicher

Symptom: Uploads laufen nicht flüssig. Ursache: 4 GB liegen unter der dokumentierten Mindestempfehlung für eine vollständige Installation. Lösung: Plane mindestens 6 GB, besser 8 GB, oder deaktiviere bei 4 GB Machine Learning.

Nur die Bilder sichern

Symptom: Nach einer Wiederherstellung fehlen Zuordnungen oder Assets. Ursache: Metadaten und Dateipfade liegen in PostgreSQL. Lösung: Sichere Datenbank und UPLOAD_LOCATION; bearbeite Dateien darin nicht manuell.

Aktuelle main-Datei blind verwenden

Symptom: Versionskonflikte nach dem Start oder Update. Ursache: Die Datei aus main muss nicht zum Release passen. Lösung: Lade die von Immich verlinkte Release-Datei.

Verifikation: So prüfst du, dass alles läuft

Führe die folgenden Prüfungen im Projektordner aus. Sie testen nicht nur den Prozessstart, sondern auch den Zugriff auf die Weboberfläche und die tatsächlich verwendeten Speicherorte.

Dieser Befehl zeigt die endgültig aufgelöste Compose-Konfiguration.

docker compose config

Erwartet ist gültiges YAML mit deinen Werten aus .env; insbesondere müssen die Bindings für Upload- und Datenbankpfad vorhanden sein.

Diese Befehle prüfen Laufzeitstatus und die letzten Servermeldungen.

docker compose ps
docker compose logs --tail=100 immich-server

Erwartet sind ein laufender Server und keine Schleife aus Neustarts. Öffne danach im Browser http://<DEINE-IP>:2283, registriere den ersten Zugang und lade ein Testbild hoch. Es soll in der Galerie erscheinen; erst dann ist die Kette aus Webdienst, Datenbank und Speicher praktisch plausibel.

Fazit

Immich Docker Compose ist keine komplizierte Installation, verlangt aber eine saubere Speicherentscheidung vor dem ersten Start. Halte PostgreSQL lokal, ändere Pfade über .env und nutze ausschließlich die Release-Dateien. Entscheidend für den langfristigen Betrieb ist ein Backup aus Datenbank und Foto-Speicher. Mit Status-, Log- und Browserprüfung erkennst du Fehler, bevor die gesamte Bibliothek importiert wird.

Quellen

• Immich: Docker Compose Installation
• Immich: Hardware- und Software-Anforderungen
• Immich: Backup and Restore
• Immich: aktuelle Release-Compose-Datei

Häufige Fragen