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

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 :

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

Sauvegarde de base

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 :

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 :

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 :

7.2 - Mettre à jour Docker Compose

Mise à jour standard

Depuis le dossier Compose :

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

Suivre :

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 :

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 :

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

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 :

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

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.
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 :

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 :

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 :

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

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 :

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

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

Lancer la commande

Docker Compose :

docker exec -it immich_server immich-admin help

TrueNAS :

sudo docker exec -it NOM_CONTENEUR_IMMICH immich-admin help

Commandes utiles

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

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 :

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

Mode maintenance

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 :

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

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/