Pourquoi auto-héberger Immich sur un VPS
Vos photos sont parmi les données les plus sensibles que vous confiez à un cloud : visages, lieux, habitudes, géolocalisation. Immich reproduit l'expérience de Google Photos, applications mobiles incluses, mais sur une infrastructure que vous possédez. Depuis la version 3.0.0, sa stack a été allégée : l'extension tierce pgvecto.rs a été supprimée au profit des index HNSW natifs de PostgreSQL (pgvector), ce qui réduit les dépendances et simplifie les sauvegardes de base de données. Un VPS dédié vous permet d'isoler le service ML gourmand, de dimensionner le stockage selon votre photothèque, et d'éviter que vos clichés ne servent à entraîner des modèles tiers. Vous restez maître du chiffrement, des sauvegardes et de l'accès.
Ce que l'auto-hébergement d'Immich apporte
- Sauvegarde automatique depuis iOS et Android dès qu'une photo est prise, comme un cloud privé.
- Reconnaissance faciale et recherche sémantique exécutées sur votre serveur, sans envoi à un tiers.
- Capacité égale à votre disque VPS : aucun quota imposé, aucune facturation au Go.
- Partage d'albums par lien sécurisé que vous contrôlez et révoquez à tout moment.
- Support multi-utilisateurs : chaque membre du foyer ou de l'équipe a sa bibliothèque isolée.
- Métadonnées EXIF, cartes et timelines conservées localement, sans exploitation publicitaire.
Prérequis matériels et logiciels
Immich est le plus exigeant de cette série à cause de son service de machine learning. Comptez au minimum 4 Go de RAM, mais 6 à 8 Go sont recommandés si la reconnaissance faciale traite une grande photothèque. 2 à 4 vCPU permettent de digérer l'indexation initiale sans bloquer l'interface. Le stockage est le facteur clé : prévoyez large, car une bibliothèque familiale dépasse vite 100 Go ; un VPS avec disque extensible est idéal. Côté logiciel : Docker et docker compose v2, un domaine (photos.votreentreprise.com), et suffisamment d'espace de swap pour absorber les pics du modèle ML lors du premier import.
Déployer Immich étape par étape
Préparer le VPS et le stockage
Mettez à jour le système, installez Docker, puis créez un point de montage dédié aux médias, par exemple /mnt/photos, séparé du disque système. Activez au moins 2 Go de swap pour le service de machine learning.
Récupérer le compose officiel et le .env
Téléchargez le docker-compose.yml et le fichier example.env du dépôt Immich avec wget. Renommez en .env, puis définissez UPLOAD_LOCATION=/mnt/photos, le mot de passe de la base et DB_DATA_LOCATION sur un volume persistant.
Comprendre les trois services (v3+)
Depuis la version 3.0.0, la stack démarre immich-server, immich-machine-learning et database (PostgreSQL avec pgvector). Redis n'est plus un service séparé — il est embarqué dans le serveur Immich. L'extension pgvecto.rs a été supprimée : ne pas utiliser l'ancienne image de base de données ghcr.io/immich-app/postgres, remplacée par l'image officielle PostgreSQL 17 avec pgvector.
Lancer la pile et créer l'administrateur
Exécutez docker compose up -d et attendez le téléchargement des images ML, volumineuses. Ouvrez le port 2283 en interne, puis créez le compte administrateur via l'assistant web avant d'inviter d'autres utilisateurs.
Sécuriser avec un reverse proxy et SSL
Placez Caddy devant le serveur : photos.votreentreprise.com { reverse_proxy immich-server:2283 }. Augmentez la taille maximale d'upload du proxy (client_max_body_size sur Nginx) car les vidéos peuvent être lourdes, sinon les envois mobiles échouent.
Configurer l'application mobile
Installez Immich depuis l'App Store ou le Play Store, saisissez https://photos.votreentreprise.com comme URL de serveur, connectez-vous, puis activez la sauvegarde automatique de la pellicule pour répliquer en continu vos nouveaux clichés.
Lors du premier import massif, lancez la génération des miniatures et des embeddings ML pendant une période creuse et surveillez la RAM avec docker stats. Si le service de machine learning sature, vous pouvez le faire pointer temporairement vers le modèle le plus léger dans les paramètres, puis repasser à un modèle plus précis une fois l'indexation initiale terminée. Cela évite que le VPS ne s'effondre sous la charge du tout premier scan.
RAM limitée ? Faites tourner Immich sans le conteneur d'IA
Si votre VPS n'a que 2 à 4 Go de RAM, retirez le service immich-machine-learning du fichier compose. Immich démarre très bien sans lui : la sauvegarde mobile, le fil chronologique, les albums, le partage, la vue cartographique et la recherche manuelle continuent tous de fonctionner — vous perdez seulement la reconnaissance faciale automatique et la recherche intelligente en langage naturel. Rajoutez le conteneur de machine learning plus tard, lorsque vous passerez à un VPS plus grand, et Immich indexera à ce moment-là votre bibliothèque existante pour la recherche par IA.
Résoudre les erreurs machine learning
Le conteneur immich-machine-learning peut devenir silencieusement injoignable pour deux raisons distinctes : une erreur de réseau Docker ou un arrêt silencieux par manque de mémoire vive. Les symptômes typiques sont des entrées comme Machine learning request to 'http://immich-machine-learning:3003' failed: fetch failed dans les journaux du serveur, ou des tâches bloquées du type Unable to run job handler (AssetDetectFaces). Le diagnostic prend moins de cinq minutes.
Diagnostiquer et corriger le service ML
Vérifier le réseau Docker
Exécutez docker network inspect immich_default et repérez si immich-server et immich-machine-learning figurent tous les deux dans la liste Containers. Si l'un est absent, vérifiez le champ networks dans votre docker-compose.yml : les deux services doivent référencer le même réseau.
Détecter un OOM silencieux
Lancez dmesg | grep -i oom pour voir si le noyau a tué un processus. Chaque OOM kill mentionne le nom du conteneur et la quantité de mémoire demandée. Un résultat vide ne confirme pas l'absence d'OOM si le système a redémarré depuis l'incident.
Consulter les journaux du conteneur ML
Exécutez docker logs immich-machine-learning --tail 50 pour observer les dernières lignes. Un arrêt propre ou une erreur de chargement de modèle y apparaîtra plus clairement qu'un OOM silencieux du noyau.
Redémarrer le service ML
Si le réseau est correct et que la RAM est suffisante, relancez uniquement ce service avec docker compose restart immich-machine-learning et observez si les tâches reprennent dans les minutes suivantes via docker logs -f immich-machine-learning.
VPS ≤ 2 Go : désactiver le machine learning
Le service ML cumule CLIP, la reconnaissance faciale et l'OCR, soit environ 2 Go de RAM au pic. Sur un VPS avec 2 Go seulement, ajoutez MACHINE_LEARNING_ENABLED=false dans votre fichier .env, puis relancez la pile avec docker compose up -d. La sauvegarde mobile, les albums et la recherche manuelle continuent de fonctionner. La reconnaissance faciale et la recherche IA s'activeront dès que vous passerez à un VPS avec 4 Go de RAM ou plus.
Migrer de la v2.4.x vers la v3.0.0 : le chemin obligatoire
La version 3.0.0 d'Immich est une rupture architecturale : pgvecto.rs est supprimé et les index vectoriels sont reconstruits nativement par pgvector (HNSW). Cette reconstruction est bloquante — la base de données recalcule tous les vecteurs de votre photothèque avant de remettre le serveur en ligne, ce qui peut prendre de plusieurs minutes à plusieurs heures selon la taille de la bibliothèque. Avant de sauter directement à la v3, vous devez obligatoirement passer par la version 1.132.3 : c'est le point de charnière qui prépare la migration des index. Partir d'une version antérieure sans passer par ce jalon provoque une erreur de migration de base de données et bloque le démarrage du serveur.
Procédure de mise à jour v2.4.x → v3
Sauvegarder la base de données avant tout
Avant toute mise à jour, exportez la base avec docker exec -t immich_postgres pg_dumpall -c -U postgres > backup_immich_avant_v3.sql. Conservez également le dossier UPLOAD_LOCATION. Une migration HNSW échouée à mi-parcours sans sauvegarde laisse la base dans un état incohérent.
Monter d'abord à la version 1.132.3
Modifiez docker-compose.yml pour utiliser la version v1.132.3 (tag exact) sur immich-server et immich-machine-learning. Lancez docker compose pull && docker compose up -d. Laissez le serveur démarrer complètement et vérifiez que les jobs de fond reprennent sans erreur dans docker logs immich-server.
Passer à l'image PostgreSQL officielle (v3 seulement)
La v3 utilise l'image officielle PostgreSQL 17 avec pgvector, et non plus l'image personnalisée ghcr.io/immich-app/postgres. Dans le docker-compose.yml fourni avec la v3, le service database pointe vers docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0 remplacé par postgres:17-bookworm avec l'extension pgvector. Utilisez le fichier compose officiel de la v3 et ne recyclez pas le fichier de la v2.
Mettre à jour vers la v3.0.0 et attendre la réindexation HNSW
Remplacez les tags par v3.0.0 et tirez les images : docker compose pull && docker compose up -d. La migration HNSW démarre automatiquement au premier lancement. Pendant cette phase, le serveur reste disponible mais la recherche intelligente et la reconnaissance faciale sont suspendues. Suivez la progression dans docker logs -f immich-server : une ligne Finished migration confirme la fin. Sur une photothèque de 50 000 photos, comptez entre 10 et 30 minutes selon le nombre de vCPU alloués.
Vérifier les jobs de fond après migration
Ouvrez l'interface web, naviguez vers Administration → Tâches et confirmez qu'aucun job n'est en état d'erreur. Si des tâches Smart Search ou Face Detection sont bloquées, relancez-les depuis l'interface. Les nouveaux vecteurs HNSW sont recalculés une seule fois : les imports ultérieurs s'indexent normalement.
Immich v2 vs v3 : ce qui change en pratique
| Aspect | v2.4.x | v3.0.0 |
|---|---|---|
| Extension vectorielle | `pgvecto.rs` (image personnalisée) | `pgvector` HNSW natif (PostgreSQL officiel) |
| Services Docker | 4 (server, ML, Redis, DB) | 3 (server, ML, DB — Redis embarqué) |
| Mise à jour directe depuis v2 | Non — passer par v1.132.3 obligatoire | Oui depuis v1.132.3 |
| Sauvegarde de la base | Dépend de l'image personnalisée | Compatible `pg_dump` standard |
| Réindexation au démarrage | Non | Oui (bloquante, durée selon taille) |
