PhotoPrism mit Docker installieren: KI-gestützte Fotoverwaltung als Google-Photos-Ersatz

Wer seine Fotos nicht bei Google, Apple oder Microsoft speichern möchte, findet in PhotoPrism eine selbst gehostete Fotoverwaltung. Sie analysiert die Bibliothek per KI: TensorFlow- und ONNX-Modelle erkennen Gesichter, vergeben Labels und sortieren Bilder nach Ort, Datum und Inhalt. Diese Anleitung zeigt, wie Sie PhotoPrism per docker compose auf einem Linux-Host oder NAS mit MariaDB als Datenbank in Betrieb nehmen.

Voraussetzungen

1. Docker Engine mit dem docker compose-Plugin (v2); eine Installationsanleitung finden Sie unter Docker und Docker Compose auf Linux installieren.
2. Linux-Host, VM oder NAS mit 64-Bit-Betriebssystem (x86_64 oder ARM64). Das Image photoprism/photoprism:armv7 für 32-Bit-ARM wird seit April 2025 nicht mehr aktualisiert.
3. Laut Hersteller mindestens 2 CPU-Kerne, 3 GB RAM und 4 GB Swap; mehr RAM beschleunigt die Indexierung. Ohne Swap beendet der Kernel den Container bei der Indexierung großer Dateien leicht wegen Speichermangels.
4. SSD-Speicher für den Storage-Ordner (Thumbnails, Index, Cache) ist dringend empfohlen; mechanische Festplatten verlängern die Indexierung erheblich.
5. Ausreichend freier Speicherplatz: Originaldateien + ca. 10–20 % Aufschlag für Thumbnails und Sidecars.
6. Für HTTPS und eigene Domain: einen vorgeschalteten Reverse Proxy wie Traefik oder Caddy – siehe Caddy als Reverse Proxy mit automatischem HTTPS.
7. Optional: curl für die Prüfschritte im Terminal.

Eckdaten auf einen Blick

Schritt 1: Projektordner anlegen

Legen Sie einen eigenen Ordner für den Stack an. Verwenden Sie in der .env absolute Pfade; relative Pfade hängen vom Arbeitsverzeichnis ab und führen im Betrieb leicht zu leeren Bibliotheken:

sudo mkdir -p /opt/photoprism
cd /opt/photoprism

Erstellen Sie die Host-Verzeichnisse für Originaldateien und Storage. Die beiden Ordner dürfen nicht ineinander liegen, sonst indiziert PhotoPrism seine eigenen Cache-Dateien als Fotos.

sudo mkdir -p /opt/photoprism/photos
sudo mkdir -p /opt/photoprism/storage

# Schreibrechte für UID 1000 (nötig, wenn Sie PHOTOPRISM_UID/user: 1000 setzen)
sudo chown -R 1000:1000 /opt/photoprism/storage

Verifizieren: ls -la /opt/photoprism/ zeigt photos/ und storage/; stat -c "%U %G" /opt/photoprism/storage gibt den Eigentümer zurück. Existiert kein Benutzer mit UID 1000, erscheint die numerische ID; das ist korrekt.

Schritt 2: .env-Datei mit Secrets anlegen

PhotoPrism liest Passwörter und Umgebungsvariablen aus der .env-Datei. Setzen Sie die Passwörter vor dem ersten Start: MariaDB übernimmt MARIADB_PASSWORD nur bei der Erstinitialisierung, spätere Änderungen erfordern einen SQL-Befehl.

# /opt/photoprism/.env
# --- PhotoPrism ---
PHOTOPRISM_ADMIN_PASSWORD=ihr-sicheres-passwort-8-bis-72-zeichen
PHOTOPRISM_SITE_URL=http://192.168.1.100:2342/

# --- MariaDB ---
MARIADB_PASSWORD=db-passwort-sicher
MARIADB_ROOT_PASSWORD=root-passwort-sicher

# --- Optionale Host-Pfade (Standardwerte werden in compose.yaml gesetzt) ---
ORIGINALS_PATH=/opt/photoprism/photos
STORAGE_PATH=/opt/photoprism/storage

Schränken Sie die Dateiberechtigungen ein:

chmod 600 /opt/photoprism/.env

Verifizieren: ls -la /opt/photoprism/.env zeigt -rw-------. Prüfen Sie mit grep PHOTOPRISM_ADMIN_PASSWORD /opt/photoprism/.env, dass das Passwort 8 bis 72 Zeichen hat.

Schritt 3: compose.yaml erstellen

Die folgende compose.yaml lehnt sich an die offizielle Vorlage an: Ein MariaDB-Healthcheck sorgt dafür, dass PhotoPrism erst nach der Datenbank startet, security_opt verhindert Blockaden durch SELinux/AppArmor, die Datenbankdateien liegen in einem benannten Volume. Secrets kommen aus der .env.

# /opt/photoprism/compose.yaml
services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    stop_grace_period: 10s
    depends_on:
      mariadb:
        condition: service_healthy
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "${PHOTOPRISM_ADMIN_PASSWORD:-bitte-aendern}"
      PHOTOPRISM_AUTH_MODE: "password"
      PHOTOPRISM_SITE_URL: "${PHOTOPRISM_SITE_URL:-http://localhost:2342/}"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_LOG_LEVEL: "info"
      PHOTOPRISM_READONLY: "false"
      PHOTOPRISM_EXPERIMENTAL: "false"
      PHOTOPRISM_DISABLE_CHOWN: "false"
      PHOTOPRISM_DISABLE_FACES: "false"
      PHOTOPRISM_DISABLE_CLASSIFICATION: "false"
      PHOTOPRISM_DISABLE_VECTORS: "false"
      PHOTOPRISM_DISABLE_RAW: "false"
      PHOTOPRISM_DETECT_NSFW: "false"
      PHOTOPRISM_UPLOAD_LIMIT: 500
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "${MARIADB_PASSWORD:-db-passwort-aendern}"
      PHOTOPRISM_SITE_CAPTION: "KI-gestützte Fotoverwaltung"
    volumes:
      - "${ORIGINALS_PATH:-./photos}:/photoprism/originals"
      - "${STORAGE_PATH:-./storage}:/photoprism/storage"
    networks:
      - photoprism-net

  mariadb:
    image: mariadb:11
    container_name: photoprism-db
    restart: unless-stopped
    stop_grace_period: 10s
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    command:
      - --innodb-buffer-pool-size=512M
      - --transaction-isolation=READ-COMMITTED
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --max-connections=512
      - --innodb-rollback-on-timeout=OFF
      - --innodb-lock-wait-timeout=120
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_INITDB_SKIP_TZINFO: "1"
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "${MARIADB_PASSWORD:-db-passwort-aendern}"
      MARIADB_ROOT_PASSWORD: "${MARIADB_ROOT_PASSWORD:-root-passwort-aendern}"
    volumes:
      - photoprism_db:/var/lib/mysql
    networks:
      - photoprism-net
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 30s
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  photoprism_db:
    driver: local

networks:
  photoprism-net:
    driver: bridge

Zwei Parameter verdienen besondere Beachtung: --transaction-isolation=READ-COMMITTED ist laut PhotoPrism-Dokumentation für MariaDB zwingend erforderlich – ohne diese Einstellung kann es zu Index-Inkonsistenzen kommen. Der --innodb-buffer-pool-size-Wert von 512 MB passt für die meisten Heimserver; bei knappem RAM reduzieren Sie ihn auf 128 bis 256 MB.

Verifizieren: docker compose config --quiet endet in /opt/photoprism/ ohne Fehler. Prüfen Sie außerdem mit docker compose config | grep PHOTOPRISM_ADMIN_PASSWORD, dass das Passwort aus der .env-Datei korrekt substituiert wurde und nicht der Platzhalter bitte-aendern erscheint.

Schritt 4: Stack starten

Starten Sie den Stack. Docker Compose lädt zunächst beide Images (photoprism/photoprism komprimiert rund 1 GB), initialisiert MariaDB und startet PhotoPrism erst nach bestandenem Healthcheck:

cd /opt/photoprism
docker compose up -d

Der erste Start dauert länger, weil PhotoPrism das Datenbankschema anlegt.

# Status beider Container prüfen
docker compose ps

# Erwartete Ausgabe:
# NAME             IMAGE                          STATUS
# photoprism       photoprism/photoprism:latest   Up X minutes
# photoprism-db    mariadb:11                     Up (healthy)
# Live-Logs verfolgen (Ctrl+C zum Beenden)
docker compose logs -f photoprism

Warten Sie, bis im Log die Zeile server: listening on 0.0.0.0:2342 erscheint und kein ERROR mit Datenbankbezug zu sehen ist.

Verifizieren: curl -i http://localhost:2342/api/v1/status liefert HTTP/1.1 200 OK und {"status":"operational"}. Alternativ: docker compose ps zeigt für beide Container Up (MariaDB zusätzlich healthy). Steht PhotoPrism auf Restarting, deutet das auf ein Datenbankproblem hin; prüfen Sie die Logs mit docker compose logs photoprism.

Schritt 5: Erste Einrichtung im Browser

Öffnen Sie im Browser die Adresse aus PHOTOPRISM_SITE_URL (z. B. http://192.168.1.100:2342/) und melden Sie sich mit admin und dem Passwort aus der .env an.

Nach dem Login empfiehlt sich folgende Reihenfolge:

1. Einstellungen prüfen: Unter Settings > General die Instanz-URL kontrollieren – sie muss mit dem Wert in PHOTOPRISM_SITE_URL übereinstimmen, sonst funktionieren geteilte Links nicht. Achten Sie auf den abschließenden Schrägstrich.
2. Erste Indexierung starten: Öffnen Sie Library > Index und klicken Sie Start. PhotoPrism durchsucht den originals-Ordner, erstellt Thumbnails und führt die KI-Analyse durch. Alternativ per CLI:

docker compose exec photoprism photoprism index --cleanup

Die Dauer der Indexierung hängt stark von der Bibliotheksgröße und der CPU-Leistung ab. Rechnen Sie auf einem aktuellen Mehrkern-System mit etwa 1 bis 3 Sekunden pro Foto.

1. Google-Takeout importieren: Google-Takeout-Archive (ZIP entpackt) ins photos-Verzeichnis legen oder via Library > Import aus dem Import-Ordner einlesen. PhotoPrism liest die Google-JSON-Metadaten automatisch aus.

Verifizieren: Nach erfolgreichem Login und gestarteter Indexierung zeigt Library > Index den Fortschritt. Unter Browse erscheinen die ersten Fotos mit Thumbnails. Nach abgeschlossener KI-Analyse sind unter Labels automatische Tags und unter People erkannte Gesichter sichtbar.

Schritt 6: Updates und Backup

Ein Update besteht aus Image-Pull und Neuerstellung der Container. PhotoPrism migriert sein Schema beim Start selbst, MARIADB_AUTO_UPGRADE=1 aktualisiert die MariaDB-Systemtabellen:

cd /opt/photoprism
docker compose pull
docker compose up -d

Für ein Datenbank-Backup nutzen Sie den eingebauten Befehl von PhotoPrism; er benötigt kein Datenbank-Passwort in der Shell:

docker compose exec -T photoprism photoprism backup -i - \
  > /opt/photoprism/backup-$(date +%Y%m%d).sql

Sichern Sie auch den Storage-Ordner (/opt/photoprism/storage/) regelmäßig – er enthält Konfiguration, Sidecars und den Thumbnail-Cache. Eine bewährte Strategie dafür beschreibt die Anleitung 3-2-1-Backup-Strategie praktisch umsetzen. Das Automatisieren von Datenbank-Backups beschreibt MySQL & PostgreSQL Backup automatisieren mit cron.

Verifizieren: Nach docker compose pull zeigt docker compose images den aktuellen Image-Digest. Nach up -d bestätigt docker compose ps wieder beide Container als Up. Migrationsmeldungen zeigt docker compose logs photoprism | grep -i migrat.

Troubleshooting / Typische Fehler

1. permission denied oder read-only file system: Der Storage-Ordner ist für den Container-Benutzer nicht beschreibbar (bei gesetztem PHOTOPRISM_UID bzw. user: 1000). Lösung: sudo chown -R 1000:1000 /opt/photoprism/storage auf dem Host ausführen.
2. PhotoPrism startet, verbindet sich aber nicht mit der Datenbank (no route to host): MariaDB ist noch nicht bereit. Das depends_on: condition: service_healthy in der compose.yaml verhindert das in der Regel – prüfen Sie, ob der MariaDB-Healthcheck nach mehreren Minuten noch fehlschlägt: docker inspect photoprism-db | grep Health.
3. Passwort-Änderung in .env hat keine Wirkung (MariaDB): Nach dem ersten Start ignoriert MariaDB Passwortänderungen per Umgebungsvariable. Das Passwort muss direkt per SQL geändert werden: docker compose exec mariadb mariadb -u root -p, dann ALTER USER 'photoprism'@'%' IDENTIFIED BY 'neues-passwort';
4. Container wird mit killed beendet (OOM-Kill): Zu wenig RAM oder Swap. Mindestens 4 GB Swap auf dem Host konfigurieren; keine harten Memory-Limits in Docker setzen solange PhotoPrism TensorFlow-Modelle lädt.
5. Geteilte Links funktionieren nicht / WebDAV schlägt fehl: PHOTOPRISM_SITE_URL stimmt nicht mit der tatsächlichen Zugriffsadresse überein. Wichtig: abschließenden Schrägstrich nicht vergessen (http://mein-server:2342/).
6. MariaDB startet nicht (Buffer-Pool-Fehler): Der Wert von --innodb-buffer-pool-size ist größer als der verfügbare RAM. Wert auf 128M oder 256M reduzieren.
7. Thumbnails nach Neustart verschwunden: Storage-Verzeichnis wurde nicht persistent gemountet. Immer einen Host-Pfad oder ein benanntes Volume für /photoprism/storage verwenden.
8. SELinux/AppArmor blockiert Volume-Zugriff (RHEL/Fedora/Ubuntu): Die security_opt-Einträge in der compose.yaml sind bereits gesetzt. Alternativ Volume-Mounts mit dem SELinux-Label :z oder :Z versehen.

Häufige Fragen

Wie starte ich die KI-Indexierung manuell?

Über die Web-UI unter Library > Index > Start oder per CLI: docker compose exec photoprism photoprism index --cleanup. Die Option --cleanup entfernt dabei verwaiste Index-Einträge für gelöschte Dateien. Gesichtserkennung und Auto-Tagging laufen dabei automatisch mit.

Brauche ich eine GPU für die KI-Funktionen?

Nein. Gesichtserkennung und Auto-Tagging laufen vollständig auf der CPU. Eine GPU beschleunigt optional die Videotranskodierung, ist aber nicht erforderlich. Auf einem Raspberry Pi 4/5 (ARM64, reguläres :latest-Image) dauert das erste Indexieren einer großen Bibliothek deutlich länger.

Kann ich meine Google-Photos-Bibliothek importieren?

Ja. Google-Takeout-Archiv herunterladen, das ZIP entpacken und den Inhalt in den konfigurierten originals-Ordner oder den import-Ordner legen. PhotoPrism liest die Google-JSON-Metadaten (Aufnahmedatum, GPS-Koordinaten, Beschreibung) automatisch aus. Der Import über Library > Import verschiebt Dateien in eine datumsorientierte Ordnerstruktur innerhalb von originals.

Was ist der Unterschied zwischen Community Edition und Membership?

Die Community Edition (AGPL) enthält die KI-Funktionen Gesichtserkennung, Auto-Tagging und Szenenerkennung und ist vollständig selbst hostbar. Kostenpflichtige Mitgliedschaften (PhotoPrism Plus bzw. Pro) schalten zusätzliche Kartenansichten, mehrere Benutzer mit Rollen und Support frei; den aktuellen Funktionsumfang nennt die Editionsübersicht des Herstellers.

Wie funktioniert die Gesichtserkennung?

PhotoPrism erkennt Gesichter beim Indexieren automatisch. Erkannte Gesichter werden nach Ähnlichkeit geclustert und unter People angezeigt. Sie versehen Cluster mit Namen; PhotoPrism verbessert daraus die Zuordnung. Die Empfindlichkeit steuern Sie über PHOTOPRISM_FACE_SIZE (minimale Gesichtsgröße in Pixeln) und PHOTOPRISM_FACE_SCORE (Qualitätsschwellenwert 1–100).

Wie sichere ich PhotoPrism regelmäßig?

Zwei Komponenten müssen gesichert werden: die Datenbank (per photoprism backup wie in Schritt 6) und der storage-Ordner mit Konfiguration, Sidecars und Thumbnail-Cache. Die Originaldateien sichern Sie wie jede andere Mediensammlung. Automatische Datenbank-Backups in storage/backup aktiviert PHOTOPRISM_BACKUP_DATABASE: "true" (Zeitplan über PHOTOPRISM_BACKUP_SCHEDULE).

Fazit

PhotoPrism bietet Gesichtserkennung, automatisches Tagging sowie Unterstützung für RAW, HEIF und Videos auf dem eigenen Server, ohne Cloud-Abhängigkeit. Der Stack aus compose.yaml und .env ist in etwa 25 Minuten betriebsbereit; planen Sie für die erste Indexierung großer Bibliotheken deutlich mehr Zeit ein. Eine Alternative mit anderem Schwerpunkt ist Immich mit Docker. Für den Betrieb über das Internet gehört ein Reverse Proxy mit HTTPS davor, etwa Traefik als Docker-Reverse-Proxy.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren – die Self-Hosting-Grundlage
2. Immich mit Docker: die selbstgehostete Google-Photos-Alternative
3. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS
4. Caddy als Reverse Proxy: Anfänger-Anleitung mit automatischem HTTPS
5. MySQL & PostgreSQL Backup automatisieren mit cron
6. 3-2-1-Backup-Strategie praktisch umsetzen
7. Ollama und Open WebUI mit Docker: lokales KI-Sprachmodell

Offizielle Quellen: PhotoPrism Docker Compose Setup · Konfigurationsoptionen · Troubleshooting Guide · GitHub Repository