# 7 - Mises à jour et maintenance

Mettre Immich à jour, gérer les changements de version et utiliser les commandes d'administration.

# 7.1 - Préparer une mise à jour

Une mise à jour Immich peut inclure des changements de schéma PostgreSQL, d'images de conteneurs, de variables ou de montages. Un downgrade n'est pas pris en charge.

## Avant toute mise à jour

1. lire les notes de version depuis la version actuelle jusqu'à la cible ;
2. relever la version du serveur et des clients mobiles ;
3. vérifier l'état des conteneurs et de PostgreSQL ;
4. déclencher un dump de base ;
5. copier ou snapshotter les médias et la configuration ;
6. vérifier l'espace libre ;
7. attendre la fin des imports et tâches critiques ;
8. prévoir une fenêtre de maintenance.

## Inventaire

```bash
docker exec immich_server immich-admin version
docker compose images
docker compose ps
docker compose config --services
grep -E '^(IMMICH_VERSION|UPLOAD_LOCATION|DB_DATA_LOCATION)=' .env
```

TrueNAS :

```bash
sudo docker ps --format '{{.Names}} {{.Image}} {{.Status}}' | grep -i immich
sudo zfs list | grep -i immich
sudo zpool status
```

## Sauvegarde de base

```bash
mkdir -p /srv/backups/immich
docker exec -t immich_postgres \
  pg_dump --clean --if-exists --dbname=immich --username=postgres \
  | gzip > /srv/backups/immich/pre-update.sql.gz
```

Adapter le conteneur, la base et l'utilisateur. Vérifier le fichier :

```bash
gzip -t /srv/backups/immich/pre-update.sql.gz
ls -lh /srv/backups/immich/pre-update.sql.gz
```

## Snapshot

Sur TrueNAS, créer des snapshots manuels des datasets Immich après le dump. Le dump présent dans `backups` doit être inclus dans le snapshot ou copié avec les médias.

## Compatibilité mobile

La documentation Immich indique que l'application mobile est généralement compatible avec la version majeure actuelle et précédente, tandis que le serveur attend la même version majeure. Mettre à jour les mobiles avant le serveur lors d'un passage majeur.

## Critères de retour

Avant de commencer, décider ce qui impose un arrêt :

- PostgreSQL ne démarre pas ;
- migration de schéma en erreur ;
- médias absents ;
- authentification impossible ;
- erreurs d'intégrité nouvelles ;
- reverse proxy ou mobile inutilisable.

Le retour consiste à restaurer une sauvegarde et des fichiers cohérents, pas à simplement remettre une ancienne image sur une base déjà migrée.

Références :

- `https://docs.immich.app/install/upgrading/`
- `https://docs.immich.app/administration/backup-and-restore/`

# 7.2 - Mettre à jour Docker Compose

## Mise à jour standard

Depuis le dossier Compose :

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

Suivre :

```bash
docker compose ps
docker compose logs -f immich-server
```

Les migrations de base peuvent prendre du temps. Ne pas interrompre un traitement simplement parce que le journal reste plusieurs minutes sur une réindexation.

## Mettre à jour les fichiers Compose

Lors d'une version majeure, comparer le fichier local au fichier officiel :

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

diff -u docker-compose.yml /tmp/immich-compose-nouveau.yml
```

Ne pas remplacer aveuglément un fichier contenant des montages GPU, bibliothèques externes ou réseaux personnalisés. Reporter les adaptations sur la nouvelle base officielle.

Télécharger aussi l'exemple d'environnement :

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

diff -u .env.example /tmp/immich-env-nouveau
```

Ne pas comparer ou partager un `.env` réel contenant des secrets.

## Passage de v2.7.5 vers v3

Procédure recommandée :

1. sauvegarder complètement v2.7.5 ;
2. restaurer ou valider la copie sur v2.7.5 si une migration d'hôte est en cours ;
3. mettre les applications mobiles à jour ;
4. lire les notes de rupture v3 ;
5. adapter Compose et les variables ;
6. passer `IMMICH_VERSION` à `v3` ;
7. lancer `docker compose pull && docker compose up -d` ;
8. vérifier schéma, comptes, albums, OAuth et médias.

## Vérifications après mise à jour

```bash
docker exec immich_server immich-admin version
docker exec immich_server immich-admin schema-check
docker compose ps
docker compose logs --tail=200
```

Puis tester interface, mobile, upload, lecture vidéo, recherche, visages, bibliothèque externe et dump PostgreSQL.

## Nettoyage différé

Après plusieurs jours de validation :

```bash
docker image prune
```

Conserver les sauvegardes pré-mise à jour selon la politique de rétention.

Référence : `https://docs.immich.app/install/upgrading/`

# 7.3 - Mettre à jour TrueNAS et migrer vers VectorChord

L'application TrueNAS gère ses images et fichiers Compose. Les changements doivent passer par le catalogue et l'écran de mise à jour.

## Avant la mise à jour TrueNAS ou Immich

- dump PostgreSQL validé ;
- snapshots des datasets `data` et `pgData` ;
- réplication terminée ;
- version actuelle notée ;
- état du pool sain ;
- P2000 visible par `nvidia-smi` ;
- fenêtre de maintenance prévue.

## Mettre l'application à jour

1. ouvrir `Apps > Installed Applications` ;
2. sélectionner Immich ;
3. lire les notes de mise à jour ;
4. lancer la mise à jour ;
5. attendre l'état `Running` ;
6. examiner tous les conteneurs ;
7. contrôler la base et l'interface.

```bash
sudo docker ps -a --format '{{.Names}} {{.Image}} {{.Status}}' | grep -i immich
sudo docker logs --tail 200 NOM_CONTENEUR_SERVEUR
sudo docker logs --tail 200 NOM_CONTENEUR_POSTGRES
```

## pgvecto.rs et VectorChord

Les anciennes installations peuvent comporter :

```text
pgvecto
pgvecto_upgrade
```

Ton installation a déjà rencontré un `pgvecto_upgrade` quittant avec le code 1. Ne pas relancer au hasard ni supprimer `pgData`.

Procédure de diagnostic :

```bash
sudo docker ps -a --format '{{.Names}} {{.Image}} {{.Status}}' | grep -Ei 'immich|pgvecto|postgres'
sudo docker logs --tail 300 NOM_CONTENEUR_PGVECTO_UPGRADE
sudo docker logs --tail 300 NOM_CONTENEUR_POSTGRES
```

Relever :

- version PostgreSQL ;
- image pgvecto.rs source ;
- version Immich ;
- première erreur réelle dans le journal ;
- espace libre et permissions du dataset.

La documentation Immich actuelle utilise VectorChord. L'image PostgreSQL officielle récente inclut les extensions nécessaires pour restaurer d'anciens dumps pgvecto.rs. Pour une application TrueNAS, suivre le chemin de migration fourni par le mainteneur du catalogue au lieu de modifier le Compose rendu.

## Après mise à jour TrueNAS

```bash
nvidia-smi
sudo docker exec NOM_CONTENEUR_IMMICH nvidia-smi
sudo zpool status
```

Vérifier aussi le port 30041, les montages externes et les ACL.

Références :

- `https://docs.immich.app/install/upgrading/`
- `https://docs.immich.app/install/truenas/`

# 7.4 - Commandes d'administration et récupération

L'image `immich-server` contient la commande `immich-admin`.

## Lancer la commande

Docker Compose :

```bash
docker exec -it immich_server immich-admin help
```

TrueNAS :

```bash
sudo docker exec -it NOM_CONTENEUR_IMMICH immich-admin help
```

## Commandes utiles

```bash
immich-admin version
immich-admin schema-check
immich-admin list-users
immich-admin reset-admin-password
immich-admin enable-password-login
immich-admin disable-password-login
immich-admin enable-oauth-login
immich-admin disable-oauth-login
immich-admin enable-maintenance-mode
immich-admin disable-maintenance-mode
immich-admin grant-admin
immich-admin revoke-admin
```

## Récupération d'un accès administrateur

```bash
docker exec -it immich_server immich-admin reset-admin-password
```

Choisir d'invalider les sessions existantes si le mot de passe a pu être compromis.

Si OIDC bloque la connexion :

```bash
docker exec -it immich_server immich-admin enable-password-login
docker exec -it immich_server immich-admin disable-oauth-login
```

## Mode maintenance

```bash
docker exec -it immich_server immich-admin enable-maintenance-mode
```

La commande affiche une URL temporaire d'accès maintenance. La protéger comme un secret.

## Changement de chemin média

Les versions récentes proposent :

```bash
immich-admin change-media-location
```

Cette commande modifie les chemins stockés en base pour un nouvel emplacement de médias. Elle ne copie aucun fichier. Avant de l'utiliser :

1. sauvegarder la base ;
2. copier et vérifier les médias ;
3. comprendre ancien et nouveau chemin vus par le conteneur ;
4. exécuter en maintenance ;
5. contrôler l'intégrité.

Pour les bibliothèques externes, conserver de préférence le même chemin interne lors d'une migration.

## Schéma

```bash
docker exec immich_server immich-admin schema-check
```

Une dérive de schéma doit être analysée avec la version et les journaux. Ne pas modifier manuellement les tables pour faire disparaître le message.

Référence : `https://docs.immich.app/administration/server-commands/`