Restaurer Immich depuis une sauvegarde Borg (Borg UI & CLI)

Méthode 1 : Restauration depuis Borg UI

#

Cette procédure s’applique à une stack Immich sauvegardée via Borg UI, avec :

• un script pre-backup qui dumpe la base PostgreSQL en SQL brut (non compressé, pour une déduplication optimale) ;
• une source Borg pointant directement vers le dossier library (les photos et vidéos originales) ;
• le volume nommé model-cache (modèles de machine learning) volontairement exclu, puisqu’il se retélécharge automatiquement.

À utiliser en cas de panne, de corruption de données, ou de migration vers un nouveau serveur — tant que Borg UI et son serveur hôte fonctionnent toujours. Pour un crash total, consultez l’article dédié : Restaurer Immich sans Borg UI.

Étapes de restauration

#

1. Arrêter la stack Immich

#

Avant tout, arrêtez complètement la stack pour qu’aucun processus n’écrive dans la bibliothèque ou la base pendant la restauration.

cd /home/olivier/stacks/immich
docker compose down

Ne redémarrez rien tant que la restauration n’est pas terminée.

2. Restaurer l’archive vers un dossier temporaire

#

Dans Borg UI : Archives → sélectionnez le repository Immich → choisissez l’archive à la date voulue → sélectionnez tout son contenu (immich-library, immich-staging) → Restore vers un dossier temporaire, par exemple :

/local/restore-immich

Ne restaurez jamais directement vers les chemins de production à cette étape.

3. Remettre en place la bibliothèque

#

Sauvegardez d’abord l’existant par précaution :

cd /home/olivier/stacks/immich
mv library library.old

Puis copiez le contenu restauré vers l’emplacement de production (celui défini par UPLOAD_LOCATION dans votre .env) :

cp -a /home/olivier/backups/.../restore-immich/immich-library \
      /home/olivier/stacks/immich/library

4. Redémarrer uniquement PostgreSQL

#

docker compose up -d database
docker compose ps   # attendre l'état "healthy"

5. Réimporter le dump SQL

#

Supprimez le contenu de la base actuelle et recréez-la (remplacez les valeurs par celles de votre fichier .env) :

docker exec -i immich_postgres psql -U <DB_USERNAME> \
  -d postgres -c "DROP DATABASE IF EXISTS <DB_DATABASE_NAME>;"

docker exec -i immich_postgres psql -U <DB_USERNAME> \
  -c "CREATE DATABASE <DB_DATABASE_NAME>;"

Puis réimportez le dump restauré :

cat /chemin/vers/restore-immich/immich-staging/db/immich-db-latest.sql | \
  docker exec -i immich_postgres psql -U <DB_USERNAME> \
  -d <DB_DATABASE_NAME>

6. Redémarrer la stack complète

#

docker compose up -d
docker compose ps   # vérifier que tout est healthy

7. Relancer les jobs de réindexation

#

Contrairement à Nextcloud, Immich n’a pas de commande occ. Une fois connecté à l’interface web, allez dans Administration → Jobs et relancez manuellement :

• Extraction de métadonnées (Metadata Extraction)
• Génération de miniatures (Thumbnail Generation)
• Reconnaissance faciale (Face Detection), si vous l’utilisez

Cela permet à Immich de resynchroniser son index avec les fichiers restaurés.

8. Vérifier que tout fonctionne

#

Connectez-vous à l’interface web d’Immich et vérifiez que vos albums, photos et métadonnées correspondent bien à la date de l’archive restaurée. Vérifiez aussi les logs :

docker logs immich_server

Points critiques à retenir

#

• Restaurez toujours vers un dossier de staging d’abord, jamais directement par-dessus les données de production.
• Le dump SQL contient la structure exacte de la base : sur un nouveau serveur, vérifiez que DB_USERNAME / DB_PASSWORD dans le .env correspondent à ce que PostgreSQL attend.
• model-cache n’a pas besoin d’être restauré : c’est un volume de modèles de machine learning qui se retélécharge automatiquement au démarrage.
• Testez cette procédure au moins une fois « à froid » avant d’en avoir besoin en situation réelle.

Méthode 2 : Restauration d’urgence en cas de crash total (sans Borg UI)

#

Cette procédure s’applique quand Borg UI lui-même n’est plus disponible : serveur détruit, disque mort, incendie, vol — tout scénario où vous repartez d’une machine vierge. Elle utilise uniquement le CLI Borg, sans interface graphique.

Pour une restauration simple (Borg UI toujours fonctionnel), consultez Restaurer Immich depuis une sauvegarde Borg UI — plus rapide et plus sûre grâce à l’interface.

Prérequis indispensables

#

Avant de commencer, vous avez besoin de trois choses qui ne sont pas dans le repository Borg lui-même :

1. La passphrase du repository Borg — sans elle, les archives sont définitivement illisibles.
2. Le docker-compose.yml et le .env de la stack Immich — ils ne sont pas sauvegardés par le script pre-backup actuel. Versionnez-les dans un dépôt Git privé séparé.
3. L’emplacement du repository (chemin local, hôte SSH, ou remote cloud via rclone).

Étapes de restauration

#

1. Préparer la nouvelle machine

#

sudo apt update
sudo apt install -y borgbackup
borg --version

2. Récupérer l’accès au repository

#

Stockage local ou disque externe reconnecté :

export BORG_REPO=/mnt/backup-externe/borg-repos/immich

Repository distant en SSH :

export BORG_REPO=ssh://user@serveur-distant:22/chemin/vers/immich

Renseignez la passphrase :

export BORG_PASSPHRASE='votre-passphrase-ici'

3. Vérifier l’intégrité et lister les archives disponibles

#

borg check "$BORG_REPO"
borg list "$BORG_REPO"

Si le message repository is locked apparaît :

borg break-lock "$BORG_REPO"

4. Extraire l’archive vers un dossier de staging

#

mkdir -p /home/olivier/restore-immich
cd /home/olivier/restore-immich
borg extract "$BORG_REPO"::NOM-DE-L-ARCHIVE

Cette commande recrée l’arborescence complète (immich-library/, immich-staging/db/immich-db-latest.sql) dans le dossier courant.

5. Reconstituer la stack Immich

#

Recréez le dossier de la stack et récupérez docker-compose.yml / .env depuis leur emplacement de sauvegarde séparé :

mkdir -p /home/olivier/stacks/immich
cd /home/olivier/stacks/immich
# Récupérez ici votre docker-compose.yml et votre .env

Copiez la bibliothèque restaurée à son emplacement :

cp -a /home/olivier/restore-immich/local/immich-library ./library

6. Démarrer uniquement PostgreSQL

#

docker compose up -d database
docker compose ps   # attendre l'état "healthy"

7. Réimporter le dump SQL

#

docker exec -i immich_postgres psql -U <DB_USERNAME> \
  -c "CREATE DATABASE <DB_DATABASE_NAME>;"

cat /home/olivier/restore-immich/local/immich-staging/db/immich-db-latest.sql | \
  docker exec -i immich_postgres psql -U <DB_USERNAME> \
  -d <DB_DATABASE_NAME>

8. Démarrer la stack complète

#

docker compose up -d
docker compose ps

9. Relancer les jobs de réindexation

#

Depuis Administration → Jobs dans l’interface web, relancez l’extraction de métadonnées et la génération de miniatures pour resynchroniser l’index avec les fichiers restaurés.

10. Réinstaller Borg UI et reconfigurer les Backup Plans

#

Une fois Immich vérifié et fonctionnel, redéployez Borg UI sur la nouvelle machine et reconfigurez les Backup Plans pour que les futures sauvegardes reprennent normalement.

Points critiques à retenir

#

• La passphrase Borg est le point de défaillance numéro un — stockez-la impérativement en dehors du serveur qu’elle protège.
• docker-compose.yml et .env ne sont pas dans la sauvegarde Borg actuelle. Prévoyez un dépôt Git privé pour ces fichiers de configuration.
• Vérifiez régulièrement que votre repository a bien une copie hors-site.
• Testez cette procédure de bout en bout au moins une fois, idéalement sur une VM isolée.