Passer au contenu principal

Développement avec les conteneurs Dev

Les conteneurs Dev offrent un environnement de développement cohérent et reproductible en utilisant des conteneurs Docker. D'un simple clic, vous pouvez démarrer un environnement de développement Immich sur Mac, Linux, Windows ou dans le cloud en utilisant les Codespaces GitHub.

Commencez rapidement !

Ouvrir dans les Codespaces GitHub

En savoir plus sur les conteneurs Dev

Prérequis​

Avant de commencer, assurez-vous d'avoir :

  • Docker Desktop (dernière version)
  • Visual Studio Code avec l'extension Dev Containers
  • Git pour cloner le dépôt
  • Au moins 8 Go de RAM (16 Go recommandés)
  • 20 Go d'espace disque libre
Environnements de développement alternatifs

Bien que ce guide se concentre sur VS Code, vous avez plusieurs options pour le développement en conteneurs Dev :

Éditeurs locaux :

Solutions basées sur le cloud :

  • GitHub Codespaces - Intégration complète avec GitHub, prend en charge devcontainer.json de manière excellente
  • GitPod - Plateforme SaaS avec support récent des conteneurs Dev (utilisation historique de gitpod.yml)

Options auto-hébergées :

  • Coder - Orienté entreprises, nécessite la connaissance de Terraform, autogéré
  • DevPod - Outil uniquement côté client avec excellent support pour devcontainer.json, fonctionne avec tout fournisseur (local, cloud ou sur site)

Services de conteneur Dev​

L'environnement de conteneur Dev se compose des services suivants :

ServiceNom du conteneurDescriptionPorts
Serveur & Webimmich-serverExécute à la fois le serveur API et l'interface Web en mode développement2283 (API)
3000 (Web)
9230 (Debug des travailleurs)
9231 (Debug API)
Base de donnéesdatabaseBase de données PostgreSQL5432
CacheredisServeur de cache Valkey6379
Machine Learningimmich-machine-learningServeur d'inférence du modèle ML d'Immich3003

Commencer​

Étape 1 : Cloner le dépôt​

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

Étape 2 : Configurer les variables d'environnement​

Les conteneurs dev Immich lisent les variables d'environnement à partir de votre environnement shell, et non à partir de fichiers .env. Cela leur permet de fonctionner dans des environnements cloud sans préconfiguration.

Configuration

En exécutant localement, si vous souhaitez créer (ou utiliser un existant) dossier de stockage DB et/ou photo, vous devez définir la variable UPLOAD_LOCATION dans votre environnement shell avant de lancer le conteneur Dev. Cela détermine où les fichiers téléchargés sont stockés et également où la base de données stocke ses données.

# Définir temporairement pour la session en cours
export UPLOAD_LOCATION=/opt/dev_upload_folder

# Ou ajouter à votre profil shell pour la persistance
# (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

Étape 3 : Lancer le conteneur Dev​

astuce

Le développement Immich utilise largement des images de base spécialisées pour son développement basé sur docker-compose. Pour cette raison, vous ne pourrez pas utiliser la commande Clone Repository in a Container Volume de VSCode.

Utilisation de l'interface utilisateur de VS Code :​

  1. Ouvrez le dépôt cloné dans VS Code
  2. Appuyez sur F1 ou Ctrl/Cmd+Maj+P pour ouvrir la palette de commandes
  3. Tapez et sélectionnez "Dev Containers : Rebuild and Reopen in Container"
  4. Sélectionnez "Immich - Backend, Frontend and ML" dans la liste
  5. Attendez que le conteneur se construise et démarre (cela peut prendre plusieurs minutes au premier lancement)

Utilisation des actions rapides de VS Code :​

  1. Ouvrez le dépôt dans VS Code
  2. Vous devriez voir une popup demandant si vous souhaitez rouvrir dans un conteneur
  3. Cliquez sur "Reopen in Container"

Utilisation de la ligne de commande :​

# Utilisation du CLI DevContainer
devcontainer up --workspace-folder .

Détails des variables d'environnement​

Comment les conteneurs Dev gèrent les variables d'environnement​

Contrairement à la configuration de développeur Immich basée sur Docker Compose qui utilise des fichiers .env, les conteneurs dev Immich lisent les variables d'environnement depuis votre environnement shell. Cela est configuré dans .devcontainer/devcontainer.json :

"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}"
}

La syntaxe ${localEnv:VARIABLE:default} lit à partir de votre environnement shell avec des valeurs par défaut facultatives.

Résolution du chemin d'emplacement des téléchargements​

La variable d'environnement UPLOAD_LOCATION contrôle où les fichiers sont stockés :

Par défaut : ./Library (relatif au répertoire docker) Résolu comme : <immich-root>/docker/Library

Montages créés :

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

Configuration de la base de données​

Ces variables ont des valeurs par défaut raisonnables (pour le développement) mais peuvent être personnalisées :

VariablePar défautDescription
DB_PASSWORDpostgresMot de passe PostgreSQL
DB_USERNAMEpostgresNom d'utilisateur PostgreSQL
DB_DATABASE_NAMEimmichNom de la base de données

Définir les variables d'environnement​

Ajoutez-les à votre profil shell (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.) :

# Obligatoire
export UPLOAD_LOCATION=./Library  # ou chemin absolu

# Optionnel (seulement si vous utilisez des valeurs non par défaut)
export DB_PASSWORD=your_password
export DB_USERNAME=your_username
export DB_DATABASE_NAME=your_database

N'oubliez pas de recharger votre configuration shell :

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

Configuration Git​

Clés SSH et authentification​

Pour utiliser vos clés SSH pour l'accès GitHub à l'intérieur du conteneur Dev :

  1. Démarrer l'agent SSH sur votre machine hôte :

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # ou chemin de votre clé

  2. VS Code transfère automatiquement votre agent SSH au conteneur

Pour des instructions détaillées, consultez le guide de VS Code sur le partage des identifiants Git.

Signature des commits​

Pour utiliser votre clé SSH pour signer les commits, consultez le guide GitHub sur la signature des commits SSH.

Flux de travail de développement​

Configuration automatique​

Lorsque le conteneur Dev démarre, il effectue automatiquement :

  1. Exécute un script post-création (container-server-post-create.sh) :

    • Ajuste les permissions de fichiers pour l'utilisateur node
    • Installe les dépendances : npm install dans tous les packages
    • Compile le SDK TypeScript : npm run build dans open-api/typescript-sdk

  2. Démarre les serveurs de développement via les tâches VS Code :

    • Immich API Server (Nest) - serveur API avec rechargement à chaud sur le port 2283
    • Immich Web Server (Vite) - interface Web avec rechargement à chaud sur le port 3000
    • Les deux serveurs surveillent les changements de fichiers et recompilent automatiquement

  3. Configure le transfert de ports :

info

La configuration du conteneur Dev remplace la commande make dev de la configuration traditionnelle. Tous les services démarrent automatiquement lorsque vous ouvrez le conteneur.

Accéder aux services​

Une fois en cours d'exécution, vous pouvez accéder à :

ServiceURLDescription
Interface Webhttp://localhost:3000Interface Web principale
APIhttp://localhost:2283Points de terminaison REST API (pas utilisés directement, l'interface Web exposera ceci sur http://localhost:3000/api
Base de donnéeslocalhost:5432PostgreSQL (nom d'utilisateur : postgres) (pas utilisé directement)

Connecter des applications mobiles​

Pour connecter l'application mobile à votre conteneur Dev :

  1. Trouvez l'adresse IP de votre machine
  2. Dans l'application mobile, utilisez : http://VOTRE_IP:3000/api
  3. Assurez-vous que votre pare-feu autorise les connexions sur le port 2283

Apporter des modifications au code​

  • Code du serveur (/server) : Les changements déclenchent un redémarrage automatique
  • Code Web (/web) : Les changements déclenchent un remplacement de module à chaud
  • Migrations de base de données : Exécutez npm run sync:sql dans le répertoire du serveur
  • Modifications de l'API : Régénérez le SDK TypeScript avec make open-api

Tests​

Exécution des tests​

Le container de développement prend en charge plusieurs façons d'exécuter les tests :

Utilisation des commandes Make (Recommandé)​

# Exécutez les tests pour des composants spécifiques
make test-server         # Tests unitaires du serveur
make test-web           # Tests unitaires web
make test-e2e           # Tests de bout en bout
make test-cli           # Tests CLI

# Exécutez tous les tests
make test-all           # Exécute les tests pour tous les composants

# Tests moyens (tests d'intégration)
make test-medium-dev    # Tests de bout en bout

Utilisation directe de NPM​

# Tests du serveur
cd /workspaces/immich/server
npm test                # Exécute tous les tests
npm run test:watch     # Mode surveillance
npm run test:cov       # Rapport de couverture

# Tests du web
cd /workspaces/immich/web
npm test               # Exécute tous les tests
npm run test:watch     # Mode surveillance

# Tests E2E
cd /workspaces/immich/e2e
npm run test           # Exécute les tests API
npm run test:web       # Exécute les tests de l'interface utilisateur web

Commandes de qualité du code​

# Linting
make lint-server        # Analyse statique du code serveur
make lint-web          # Analyse statique du code web
make lint-all          # Analyse statique de tous les composants

# Formatage
make format-server      # Formate le code serveur
make format-web        # Formate le code web
make format-all        # Formate tout le code

# Vérification des types
make check-server       # Vérification des types pour le serveur
make check-web         # Vérification des types pour le web
make check-all         # Vérifie tous les composants

# Vérification complète
make hygiene-all       # Exécute lint, format, vérification, synchronisation SQL et audit

Commandes Make supplémentaires​

# Commandes de build
make build-server       # Build du serveur
make build-web         # Build de l'application web
make build-all         # Build complet

# Génération de l'API
make open-api          # Génère les spécifications OpenAPI
make open-api-typescript # Génère le SDK TypeScript
make open-api-dart     # Génère le SDK Dart

# Base de données
make sql               # Synchronise le schéma de la base de données

# Dépendances
make install-server    # Installe les dépendances du serveur
make install-web      # Installe les dépendances web
make install-all      # Installe toutes les dépendances

Debugging​

Le container de développement est préconfiguré pour le débogage :

  1. Débogage du serveur API :

    • Placez des points d'arrêt dans VS Code
    • Appuyez sur F5 ou utilisez le panneau "Run and Debug"
    • Sélectionnez la configuration "Attach to Server"
    • Port de débogage : 9231

  2. Débogage des Workers :

    • Utilisez la configuration "Attach to Workers"
    • Port de débogage : 9230

  3. Débogage du Web :

    • Utilisez les outils de développement du navigateur
    • Le débogueur de VS Code pour les extensions Chrome/Edge est pris en charge

Dépannage​

Problèmes courants​

Erreurs de permission​

Problème : Erreurs EACCES ou permission refusée
Solution :

  • Le container de développement s'exécute en tant qu'utilisateur node (UID 1000)
  • Si l'UID de votre hôte diffère, vous pouvez rencontrer des problèmes de permissions
  • Essayez de reconstruire le container : "Dev Containers: Rebuild Container"

Le container ne démarre pas​

Problème : Le container de développement ne parvient pas à démarrer ou à se construire
Solution :

  1. Vérifiez si Docker est en cours d'exécution : docker ps
  2. Nettoyez les ressources Docker : docker system prune -a
  3. Vérifiez l'espace disque disponible
  4. Consultez les limites des ressources Docker Desktop

Port déjà utilisé​

Problème : "Port 3000/2283 is already in use"
Solution :

  1. Recherchez les services en conflit : lsof -i :3000 (macOS/Linux)
  2. Arrêtez les services en conflit ou modifiez le mappage des ports
  3. Redémarrez Docker Desktop

Emplacement de téléchargement non défini​

Problème : Erreurs concernant l'absence de UPLOAD_LOCATION
Solution :

  1. Définissez la variable d'environnement : export UPLOAD_LOCATION=./Library
  2. Ajoutez-la à votre profil shell pour persistance
  3. Redémarrez votre terminal et VS Code

Échec de connexion à la base de données​

Problème : Impossible de se connecter à PostgreSQL
Solution :

  1. Assurez-vous que tous les conteneurs sont en cours d'exécution : docker ps
  2. Vérifiez les logs : "Dev Containers: Show Container Log"
  3. Vérifiez que les identifiants de la base de données correspondent aux variables d'environnement

Obtenir de l'aide​

Si vous rencontrez des problèmes :

  1. Consultez les logs du container : View → Output → Sélectionnez "Dev Containers"
  2. Reconstruisez sans cache : "Dev Containers: Rebuild Container Without Cache"
  3. Consultez les problèmes Docker courants
  4. Posez vos questions sur Discord dans le canal #help-desk-support

Développement mobile​

Bien que le container de développement soit orienté vers le développement serveur et web, vous pouvez connecter des applications mobiles pour les tester :

Connexion des apps iOS/Android​

  1. Assurez-vous que l'API est accessible :

    # Trouvez l'IP de votre machine
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows (dans WSL2)
    ip addr show eth0

  2. Configurez l'app mobile :

    • URL du serveur : http://VOTRE_IP:2283/api
    • Assurez-vous que le pare-feu autorise le port 2283

  3. Pour un développement mobile complet, consultez le guide de développement mobile, qui couvre :

    • Configuration de Flutter
    • Exécution sur émulateurs/appareils
    • Débogage spécifique au mobile

Configuration avancée​

Extensions VS Code personnalisées​

Ajoutez des extensions à .devcontainer/devcontainer.json :

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

Services supplémentaires​

Pour ajouter des services (par exemple, Redis Commander), modifiez :

  1. /docker/docker-compose.dev.yml - Ajoutez une définition de service
  2. /.devcontainer/server/container-compose-overrides.yml - Ajoutez des substitutions si nécessaire

Limites des ressources​

Ajustez les ressources Docker Desktop :

  • macOS/Windows : Docker Desktop → Paramètres → Ressources
  • Linux : Modifiez la configuration du démon Docker

Recommandations minimales :

  • CPU : 4 cœurs
  • Mémoire : 8 Go
  • Disque : 20 Go

Étapes suivantes​