Zum Hauptinhalt springen

Entwicklung mit Dev Containers

Dev Containers bieten eine konsistente, reproduzierbare Entwicklungsumgebung mithilfe von Docker-Containern. Mit einem einzigen Klick können Sie eine Immich-Entwicklungsumgebung auf Mac, Linux, Windows oder in der Cloud mit GitHub Codespaces starten.

Schnell anfangen!

Im GitHub Codespaces öffnen

Erfahren Sie mehr über Dev Containers

Voraussetzungen​

Bevor Sie starten, stellen Sie sicher, dass Sie Folgendes haben:

  • Docker Desktop (neueste Version)
  • Visual Studio Code mit der Dev Containers Erweiterung
  • Git zum Klonen des Repositorys
  • Mindestens 8GB RAM (16GB empfohlen)
  • 20GB freier Speicherplatz
Alternative Entwicklungsumgebungen

Während dieser Leitfaden sich auf VS Code konzentriert, gibt es viele Optionen für Dev Container-Entwicklung:

Lokale Editoren:

Cloud-basierte Lösungen:

  • GitHub Codespaces - Vollständig integriert mit GitHub, hervorragende Unterstützung für devcontainer.json
  • GitPod - SaaS-Plattform mit aktueller Dev Container-Unterstützung (historisch wurde gitpod.yml verwendet)

Selbsthostbare Optionen:

  • Coder - Unternehmensorientiert, erfordert Kenntnisse in Terraform, selbstverwaltet
  • DevPod - Nur Client-Tool mit hervorragender Unterstützung für devcontainer.json, funktioniert mit jedem Anbieter (lokal, Cloud oder Vor-Ort)

Dev Container Dienste​

Die Dev Container Umgebung besteht aus den folgenden Diensten:

DienstContainer-NameBeschreibungPorts
Server & Webimmich-serverFührt sowohl den API-Server als auch das Web-Frontend im Entwicklungsmodus aus2283 (API)
3000 (Web)
9230 (Workers Debug)
9231 (API Debug)
DatenbankdatabasePostgreSQL-Datenbank5432
CacheredisValkey-Cache-Server6379
Maschinelles Lernenimmich-machine-learningImmich ML-Modell-Inferenz-Server3003

Erste Schritte​

Schritt 1: Klonen des Repositorys​

git clone https://github.com/immich-app/immich.git
cd immich

Schritt 2: Umgebungsvariablen konfigurieren​

Die immich Dev Containers lesen Umgebungsvariablen aus Ihrer Shell-Umgebung und nicht aus .env-Dateien. Dadurch können sie in Cloud-Umgebungen ohne vorherige Konfiguration funktionieren.

Konfiguration

Wenn Sie lokal arbeiten und eine (oder eine vorhandene) DB- und/oder Foto-Speicherordner erstellen möchten, müssen Sie die Variable UPLOAD_LOCATION in Ihrer Shell-Umgebung setzen, bevor Sie den Dev Container starten. Diese bestimmt, wo hochgeladene Dateien gespeichert werden und auch wo die DB ihre Daten speichert.

# Temporär für die aktuelle Sitzung setzen
export UPLOAD_LOCATION=/opt/dev_upload_folder

# Oder dauerhaft zu Ihrem Shell-Profil hinzufügen
# (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

Schritt 3: Dev Container starten​

Tipp

Immich Entwicklung nutzt intensiv spezialisierte Basisbilder für die docker-compose-basierte Entwicklung. Aus diesem Grund können Sie den Befehl Repository in Container Volume klonen von VSCode nicht verwenden.

Verwendung der VS Code-Benutzeroberfläche:​

  1. Öffnen Sie das geklonte Repository in VS Code
  2. Drücken Sie F1 oder Strg/Cmd+Shift+P, um die Befehlspalette zu öffnen
  3. Geben Sie "Dev Containers: Rebuild and Reopen in Container" ein und wählen Sie es aus
  4. Wählen Sie "Immich - Backend, Frontend and ML" aus der Liste
  5. Warten Sie, bis der Container gebaut und gestartet wird (dies kann beim ersten Start einige Minuten dauern)

Verwendung von VS Code Quick Actions:​

  1. Öffnen Sie das Repository in VS Code
  2. Sie sollten ein Popup sehen, das fragt, ob Sie in einem Container wieder öffnen möchten
  3. Klicken Sie auf "Reopen in Container"

Verwendung der Kommandozeile:​

# Verwendung der DevContainer CLI
devcontainer up --workspace-folder .

Details zu Umgebungsvariablen​

Wie Dev Containers Umgebungsvariablen handhaben​

Anders als das Immich-Entwickler-Setup, das auf Docker Compose basiert und .env-Dateien verwendet, lesen Immich Dev Containers die Umgebungsvariablen aus Ihrer Shell-Umgebung. Dies ist in .devcontainer/devcontainer.json konfiguriert:

"remoteEnv": {
    "UPLOAD_LOCATION": "${localEnv:UPLOAD_LOCATION:./Library}",
    "DB_PASSWORD": "${localEnv:DB_PASSWORD:postgres}",
    "DB_USERNAME": "${localEnv:DB_USERNAME:postgres}",
    "DB_DATABASE_NAME": "${localEnv:DB_DATABASE_NAME:immich}"
}

Die Syntax ${localEnv:VARIABLE:default} liest aus Ihrer Shell-Umgebung mit optionalen Standardwerten.

Upload-Speicherort Pfadauflösung​

Die Umgebungsvariable UPLOAD_LOCATION steuert, wo Dateien gespeichert werden:

Standard: ./Library (relativ zum docker-Verzeichnis) Aufgelöst zu: <immich-root>/docker/Library

Erstellte Bind-Mounts:

# Aus .devcontainer/server/container-compose-overrides.yml
- ${UPLOAD_LOCATION-./Library}/photos:/workspaces/immich/server/upload
- ${UPLOAD_LOCATION-./Library}/postgres:/var/lib/postgresql/data

Datenbankkonfiguration​

Diese Variablen haben sinnvolle Standardwerte (für Entwicklung), können aber angepasst werden:

VariableStandardBeschreibung
DB_PASSWORDpostgresPostgreSQL-Passwort
DB_USERNAMEpostgresPostgreSQL-Benutzername
DB_DATABASE_NAMEimmichDatenbankname

Umgebungsvariablen setzen​

Fügen Sie diese Ihrem Shell-Profil hinzu (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.):

# Erforderlich
export UPLOAD_LOCATION=./Library  # oder absoluter Pfad

# Optional (nur bei Verwendung von nicht-Standardwerten)
export DB_PASSWORD=your_password
export DB_USERNAME=your_username
export DB_DATABASE_NAME=your_database

Vergessen Sie nicht, Ihre Shell-Konfiguration neu zu laden:

source ~/.bashrc  # oder ~/.zshrc, etc.

Git-Konfiguration​

SSH-Schlüssel und Authentifizierung​

Um Ihre SSH-Schlüssel für den GitHub-Zugriff innerhalb des Dev Containers zu verwenden:

  1. Starten Sie den SSH-Agent auf Ihrem Host-Computer:

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # oder Ihr Schlüsselpfad

  2. VS Code leitet Ihren SSH-Agent automatisch an den Container weiter

Für detaillierte Anweisungen, siehe den VS Code-Leitfaden zum Teilen von Git-Credentials.

Commit-Signierung​

Um Ihren SSH-Schlüssel für die Commit-Signierung zu verwenden, siehe den GitHub-Leitfaden zur SSH-Commit-Signierung.

Entwicklungsworkflow​

Automatische Einrichtung​

Beim Start des Dev Containers wird automatisch:

  1. Post-Create-Skript ausgeführt (container-server-post-create.sh):

    • Anpassung der Dateiberechtigungen für den node-Benutzer
    • Installation von Abhängigkeiten: npm install in allen Paketen
    • TypeScript-SDK builden: npm run build in open-api/typescript-sdk

  2. Entwicklungsserver starten über VS Code Aufgaben:

    • Immich API-Server (Nest) - API-Server mit Hot-Reloading auf Port 2283
    • Immich Web-Server (Vite) - Web-Frontend mit Hot-Reloading auf Port 3000
    • Beide Server überwachen Dateiveränderungen und kompilieren automatisch neu

  3. Portweiterleitung einrichten:

Info

Die Dev Container Einrichtung ersetzt den Befehl make dev aus der traditionellen Einrichtung. Alle Dienste starten automatisch, wenn Sie den Container öffnen.

Dienste zugreifen​

Sobald alles läuft, können Sie auf Folgendes zugreifen:

DienstURLBeschreibung
Web-UIhttp://localhost:3000Haupt-Web-Oberfläche
APIhttp://localhost:2283REST-API-Endpunkte (Nicht direkt verwendet, Web-UI stellt dies unter http://localhost:3000/api bereit)
Datenbanklocalhost:5432PostgreSQL (Benutzername: postgres) (Nicht direkt verwendet)

Mobile Apps verbinden​

Um die mobile App mit Ihrem Dev Container zu verbinden:

  1. Finden Sie die IP-Adresse Ihres Computers
  2. Verwenden Sie in der mobilen App: http://IHRE_IP:3000/api
  3. Stellen Sie sicher, dass Ihre Firewall Verbindungen auf Port 2283 zulässt

Änderungen am Code vornehmen​

  • Server-Code (/server): Änderungen lösen automatischen Neustart aus
  • Web-Code (/web): Änderungen lösen Hot-Modul-Austausch aus
  • Datenbankmigrationen: Führen Sie npm run sync:sql im Serververzeichnis aus
  • API-Änderungen: Regenerieren Sie das TypeScript-SDK mit make open-api

Tests​

Tests ausführen​

Der Dev Container unterstützt verschiedene Methoden, um Tests auszuführen:

Verwendung von Make-Befehlen (empfohlen)​

# Tests für spezifische Komponenten ausführen
make test-server         # Server-Unit-Tests
make test-web           # Web-Unit-Tests
make test-e2e           # End-to-End-Tests
make test-cli           # CLI-Tests

# Alle Tests ausführen
make test-all           # Führt Tests für alle Komponenten aus

# Integrationstests
make test-medium-dev    # End-to-End-Tests

Direkte Verwendung von NPM​

# Server-Tests
cd /workspaces/immich/server
npm test                # Alle Tests ausführen
npm run test:watch     # Watch-Modus
npm run test:cov       # Berichterstellung zur Abdeckung

# Web-Tests
cd /workspaces/immich/web
npm test               # Alle Tests ausführen
npm run test:watch     # Watch-Modus

# E2E-Tests
cd /workspaces/immich/e2e
npm run test           # API-Tests ausführen
npm run test:web       # Web-UI-Tests ausführen

Befehle zur Codequalität​

# Linting
make lint-server        # Server-Code Linting
make lint-web          # Web-Code Linting
make lint-all          # Linting aller Komponenten

# Formatierung
make format-server      # Server-Code formatieren
make format-web        # Web-Code formatieren
make format-all        # Code aller Komponenten formatieren

# Typprüfung
make check-server       # Typpprüfung für den Server
make check-web         # Typpprüfung für das Web
make check-all         # Typpprüfung aller Komponenten

# Vollständige Hygieneüberprüfung
make hygiene-all       # Führt Linting, Formatierung, Typpprüfung, SQL-Synchronisierung und Audit durch

Zusätzliche Make-Befehle​

# Build-Befehle
make build-server       # Server bauen
make build-web         # Webanwendung bauen
make build-all         # Alles bauen

# API-Generierung
make open-api          # OpenAPI-Spezifikationen generieren
make open-api-typescript # TypeScript-SDK generieren
make open-api-dart     # Dart-SDK generieren

# Datenbank
make sql               # Datenbankschema synchronisieren

# Abhängigkeiten
make install-server    # Server-Abhängigkeiten installieren
make install-web      # Web-Abhängigkeiten installieren
make install-all      # Alle Abhängigkeiten installieren

Debugging​

Der Dev Container ist vorkonfiguriert für Debugging:

  1. API-Server-Debugging:

    • Breakpoints in VS Code setzen
    • Drücken Sie F5 oder verwenden Sie das Panel "Run and Debug"
    • Wählen Sie die Konfiguration "Attach to Server"
    • Debug-Port: 9231

  2. Worker-Debugging:

    • Verwenden Sie die Konfiguration "Attach to Workers"
    • Debug-Port: 9230

  3. Web-Debugging:

    • Verwenden Sie die DevTools des Browsers
    • VS Code-Debugger für Chrome/Edge-Erweiterungen werden unterstützt

Fehlerbehebung​

Häufige Probleme​

Berechtigungsfehler​

Problem: EACCES oder Berechtigungsverweigerung Lösung:

  • Der Dev Container läuft als node-Benutzer (UID 1000)
  • Wenn Ihre Host-UID abweicht, können Berechtigungsprobleme auftreten
  • Versuchen Sie, den Container neu zu erstellen: "Dev Containers: Rebuild Container"

Container startet nicht​

Problem: Dev Container kann nicht gestartet oder erstellt werden Lösung:

  1. Überprüfen, ob Docker läuft: docker ps
  2. Docker-Ressourcen bereinigen: docker system prune -a
  3. Freien Speicherplatz überprüfen
  4. Ressourcenlimits in Docker Desktop überprüfen

Port wird bereits verwendet​

Problem: "Port 3000/2283 wird bereits verwendet" Lösung:

  1. Konfliktbehaftete Dienste prüfen: lsof -i :3000 (macOS/Linux)
  2. Konfliktbehaftete Dienste beenden oder Port-Mappings ändern
  3. Docker Desktop neu starten

Upload-Standort nicht festgelegt​

Problem: Fehler über fehlenden UPLOAD_LOCATION Lösung:

  1. Umgebungsvariable setzen: export UPLOAD_LOCATION=./Library
  2. Zu Ihrem Shell-Profil hinzufügen für Persistenz
  3. Terminal und VS Code neu starten

Datenbankverbindung fehlt​

Problem: Verbindung zur PostgreSQL-Datenbank kann nicht hergestellt werden Lösung:

  1. Sicherstellen, dass alle Container laufen: docker ps
  2. Protokolle überprüfen: "Dev Containers: Show Container Log"
  3. Überprüfen, ob Datenbankanmeldeinformationen den Umgebungsvariablen entsprechen

Unterstützung erhalten​

Falls Sie Probleme haben:

  1. Container-Protokolle prüfen: Ansicht → Ausgabe → "Dev Containers" auswählen
  2. Neuaufbau ohne Cache: "Dev Containers: Rebuild Container Without Cache"
  3. Häufige Docker-Probleme überprüfen
  4. Im Discord #help-desk-support-Kanal fragen

Mobile Entwicklung​

Während sich der Dev Container auf Server- und Webentwicklung konzentriert, können Sie mobile Anwendungen zum Testen verbinden:

Verbinden von iOS/Android-Apps​

  1. API-Verfügbarkeit sicherstellen:

    # IP-Adresse Ihres Rechners herausfinden
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows (in WSL2)
    ip addr show eth0

  2. Mobile App konfigurieren:

    • Server-URL: http://YOUR_IP:2283/api
    • Sicherstellen, dass die Firewall Port 2283 zulässt

  3. Für die vollständige mobile Entwicklung, siehe den Mobile Development Guide, der Folgendes abdeckt:

    • Flutter-Einrichtung
    • Ausführen auf Emulatoren/Geräten
    • Spezielle Debugging-Tools für mobile Anwendungen

Erweiterte Konfiguration​

Anpassung der VS Code-Erweiterungen​

Hinzufügen von Erweiterungen zu .devcontainer/devcontainer.json:

"customizations": {
  "vscode": {
    "extensions": [
      "your.extension-id"
    ]
  }
}

Zusätzliche Dienste​

Um Dienste hinzuzufügen (z. B. Redis Commander), bearbeiten Sie:

  1. /docker/docker-compose.dev.yml - Dienstdefinition hinzufügen
  2. /.devcontainer/server/container-compose-overrides.yml - Falls nötig, Überschreibungen hinzufügen

Ressourcenbeschränkungen​

Docker-Desktop-Ressourcen anpassen:

  • macOS/Windows: Docker Desktop → Einstellungen → Ressourcen
  • Linux: Docker-Daemon-Konfiguration ändern

Empfohlene Mindestanforderungen:

  • CPU: 4 Kerne
  • Speicher: 8GB
  • Festplatte: 20GB

Nächste Schritte​