# 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

```bash
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 :

```bash
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

```bash
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

```bash
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

```bash
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 :

```bash
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

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

Si un GPU NVIDIA sera utilisé :

```bash
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 :

- `https://docs.immich.app/install/docker-compose/`
- `https://docs.immich.app/install/requirements/`

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

## Télécharger les fichiers officiels

```bash
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 :

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

## Configurer .env

```dotenv
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 :

```bash
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 :

```dotenv
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 :

```dotenv
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

```bash
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

```bash
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` :

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

## Contrôler l'état

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

Suivre le serveur :

```bash
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 :

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

Ouvrir ensuite :

```text
http://ADRESSE_DU_SERVEUR:2283
```

## Examiner un service en erreur

```bash
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 :

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

## Vérifier les montages

```bash
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 :

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

## Commandes de cycle de vie

```bash
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 :

```bash
docker compose up -d
```

Si nécessaire :

```bash
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 :

```text
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 :

```text
{{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

- envoyer une petite photo depuis le mobile ;
- vérifier sa présence dans la chronologie ;
- ouvrir la photo et contrôler les métadonnées ;
- regarder les tâches dans `Administration > Jobs` ;
- vérifier la création de miniatures ;
- tester la recherche après le traitement machine learning ;
- déclencher une sauvegarde de base manuelle.

## Contrôle serveur

```bash
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 :

- sauvegarder `.env` et `docker-compose.yml` ;
- déclencher un dump PostgreSQL ;
- vérifier le chemin réel des médias ;
- préparer la copie distante ;
- documenter la version Immich.

Références :

- `https://docs.immich.app/install/post-install/`
- `https://docs.immich.app/features/mobile-backup/`