2 - Installation avec Docker Compose

Déployer Immich sur un serveur Linux avec la méthode recommandée Docker Compose.

2.1 - Préparer Linux et Docker

Docker Compose est la méthode recommandée par Immich pour un déploiement Linux standard.

Préparer le serveur

sudo apt update
sudo apt upgrade
sudo apt install ca-certificates curl wget openssl rsync

Installer Docker Engine depuis le dépôt officiel Docker correspondant à la distribution. Vérifier ensuite :

docker --version
docker compose version
docker info

La commande attendue est docker compose avec un espace. L'ancien exécutable docker-compose peut être incompatible avec le fichier officiel actuel.

Créer l'arborescence

sudo mkdir -p /srv/immich/{app,data,postgres}
sudo chown -R "$USER":"$USER" /srv/immich/app

Définir séparément les permissions des données et de PostgreSQL selon les UID réellement utilisés par les conteneurs. Ne pas appliquer chmod 777.

Vérifier le stockage

df -hT /srv/immich
df -i /srv/immich
findmnt /srv/immich

La base PostgreSQL doit rester sur un stockage local fiable. Les partages réseau ne sont pas pris en charge pour DB_DATA_LOCATION dans le déploiement Compose officiel.

Heure et réseau

timedatectl
getent hosts ghcr.io
curl -I https://github.com

Le serveur doit pouvoir télécharger les images depuis GitHub Container Registry et les modèles de machine learning.

Autoriser Docker sans sudo

Option facultative :

sudo usermod -aG docker "$USER"

Fermer puis rouvrir la session. L'appartenance au groupe Docker donne des privilèges proches de root. Elle doit rester limitée aux administrateurs.

Contrôles avant installation

docker run --rm hello-world
docker compose version
free -h
lscpu

Si un GPU NVIDIA sera utilisé :

nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

Le second test nécessite le NVIDIA Container Toolkit et une image disponible. Adapter la version CUDA au pilote installé si nécessaire.

Références :

2.2 - Télécharger Compose et configurer .env

Télécharger les fichiers officiels

cd /srv/immich/app

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

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

Conserver une copie avant modification :

cp -a docker-compose.yml docker-compose.yml.original
cp -a .env .env.original

Configurer .env

UPLOAD_LOCATION=/srv/immich/data
DB_DATA_LOCATION=/srv/immich/postgres
TZ=Europe/Paris
IMMICH_VERSION=v3
DB_PASSWORD=REMPLACER_PAR_UN_SECRET_ALPHANUMERIQUE
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

La documentation recommande un mot de passe PostgreSQL composé de lettres et chiffres afin d'éviter les problèmes d'interprétation par Docker.

Générer un secret :

openssl rand -hex 24

Ne pas afficher ou partager le fichier .env complet après y avoir ajouté le secret.

Version fixe ou version majeure

Pour une nouvelle installation stable :

IMMICH_VERSION=v3

Pour restaurer une ancienne instance v2.7.5, il peut être préférable de démarrer avec la version exacte de la source :

IMMICH_VERSION=v2.7.5

Après validation de la restauration, lire les notes de version et effectuer la montée vers v3. Ne jamais tenter un downgrade d'une base déjà migrée vers une version plus récente.

Valider le fichier Compose

docker compose config --quiet
docker compose config > /tmp/immich-compose-rendu.yml

La seconde commande développe les variables. Le fichier rendu peut donc contenir des secrets et doit rester local puis être supprimé après contrôle.

Protéger la configuration

chmod 600 .env
chmod 644 docker-compose.yml

Sauvegarder .env et docker-compose.yml dans un emplacement chiffré. Le mot de passe de base et les chemins sont nécessaires pour une reconstruction fidèle.

Référence : https://docs.immich.app/install/docker-compose/

2.3 - Démarrer et contrôler les conteneurs

Démarrer Immich

Depuis le dossier contenant .env et docker-compose.yml :

cd /srv/immich/app
docker compose pull
docker compose up -d

Contrôler l'état

docker compose ps
docker compose images
docker compose logs --tail=100

Suivre le serveur :

docker compose logs -f immich-server

Quitter le suivi avec Ctrl+C. Cela n'arrête pas le conteneur.

Tester le port

Le déploiement Compose officiel utilise normalement le port 2283 :

ss -ltnp | grep 2283
curl -I http://127.0.0.1:2283

Ouvrir ensuite :

http://ADRESSE_DU_SERVEUR:2283

Examiner un service en erreur

docker compose ps -a
docker compose logs --tail=200 database
docker compose logs --tail=200 immich-server
docker compose logs --tail=200 immich-machine-learning

Le service PostgreSQL peut porter un autre nom dans une ancienne configuration. Utiliser :

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Vérifier les montages

docker inspect immich_server --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
docker exec -it immich_server sh -lc 'ls -la /data'

Les dossiers suivants doivent être accessibles :

/data/upload
/data/library
/data/thumbs
/data/profile
/data/encoded-video
/data/backups

Commandes de cycle de vie

docker compose stop
docker compose start
docker compose restart immich-server
docker compose down

docker compose down supprime les conteneurs et réseaux du projet, mais les bind mounts externes restent normalement présents. Ne pas ajouter -v sans avoir vérifié les volumes, car cette option supprime les volumes gérés par Docker.

Après modification de .env

Un simple redémarrage ne remplace pas toujours l'environnement du conteneur :

docker compose up -d

Si nécessaire :

docker compose up -d --force-recreate

Référence : https://docs.immich.app/install/environment-variables/

2.4 - Première connexion et configuration initiale

Créer le compte administrateur

Le premier compte enregistré devient administrateur. Accéder à l'interface, cliquer sur le bouton de démarrage et créer ce compte avec une adresse maîtrisée et un mot de passe unique.

Créer ensuite les autres utilisateurs depuis :

Administration > Users

Régler les paramètres essentiels

Dans Administration > Settings :

  1. vérifier le fuseau horaire et les paramètres généraux ;
  2. configurer la sauvegarde automatique PostgreSQL ;
  3. choisir le comportement de transcodage vidéo ;
  4. vérifier les paramètres de machine learning ;
  5. définir la périodicité des bibliothèques externes ;
  6. examiner les tâches nocturnes et l'intégrité.

Modèle de stockage

Le modèle de stockage peut organiser les fichiers selon une structure lisible. Exemple :

{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}

Tester le résultat affiché dans Immich avant d'appliquer une migration de stockage à une grande bibliothèque. Le changement déplace des fichiers et exige des permissions correctes.

Application mobile

  1. Installer l'application officielle Android ou iOS.
  2. Saisir l'URL complète du serveur, idéalement en HTTPS.
  3. Se connecter.
  4. Choisir les albums à sauvegarder.
  5. Vérifier les règles Wi-Fi, données mobiles et arrière-plan.
  6. Laisser l'application ouverte lors du premier envoi massif.

Premier test de bout en bout

Contrôle serveur

docker compose ps
docker compose logs --tail=100 immich-server
find /srv/immich/data -maxdepth 2 -type f | head

Sauvegarde initiale

Avant d'importer toute la photothèque :

Références :