Pour restaurer un volume nommé Docker Compose sur macOS, arrêtez les services qui y écrivent, identifiez le nom exact du volume Docker et extrayez l'archive de sauvegarde dans ce volume à l'aide d'un conteneur temporaire. Docker Desktop conserve les volumes Linux à l'intérieur de sa machine virtuelle Linux ; utilisez donc la CLI Docker pour y accéder plutôt que d'essayer de modifier les fichiers internes de Docker dans le Finder. Le guide des volumes de Docker explique la méthode de restauration basée sur des conteneurs, et la présentation de la mise en réseau de Docker Desktop décrit la machine virtuelle Linux utilisée sur Mac.

Avant de restaurer : vérifiez l'archive et le projet Compose

Assurez-vous que Docker Desktop est en cours d'exécution, puis ouvrez le Terminal et placez-vous dans le répertoire contenant votre fichier Compose. Recherchez l'archive dans le Finder ou confirmez son nom dans le Terminal. Les exemples ci-dessous supposent qu'elle s'appelle backup.tar dans un dossier nommé backup-files ; ajustez ces valeurs pour correspondre à vos fichiers.

Inspectez le contenu de l'archive avant de l'extraire. Cela vous aide à déterminer si les fichiers sont stockés directement à la racine de l'archive ou sous un répertoire parent tel que data/.

tar -tf "$HOME/backup-files/backup.tar" | head -30

La commande head limite la liste aux 30 premiers chemins ; elle ne modifie pas l'archive. Notez si les chemins commencent par un préfixe de répertoire. Vous devrez extraire le bon niveau dans le répertoire de données de l'application. L'exemple documenté par Docker utilise --strip 1 car son archive contient un répertoire de premier niveau ; n'utilisez pas cette option automatiquement si votre archive n'a pas un tel préfixe. L'exemple de restauration de Docker montre comment le chemin d'extraction affecte l'agencement restauré.

Identifier le nom exact du volume

Une clé de volume Compose telle que db-data peut ne pas être le nom complet du volume Docker. Compose le préfixe généralement avec le nom du projet, mais un volume configuré avec name: ou external: true peut utiliser un autre nom. La référence des volumes Compose explique ces options de dénomination.

Listez les volumes et inspectez la configuration Compose pour déterminer celui que votre service utilise :

docker volume ls
docker compose config

Dans la configuration Compose générée, repérez le mappage de volume du service et le nom de volume résolu. Si vous devez inspecter un candidat, exécutez docker volume inspect VOLUME_NAME, en remplaçant VOLUME_NAME par le nom réel. Confirmez qu'il appartient bien au projet et au service prévus avant de continuer ; restaurer dans le mauvais volume peut écraser des données non liées.

Arrêter les processus d'écriture et restaurer la sauvegarde

Arrêtez les services Compose avant la restauration afin que l'application ne modifie pas les fichiers pendant l'extraction. Exécuter docker compose down arrête et supprime les conteneurs et les réseaux du projet ; par défaut, cela conserve les volumes nommés. Évitez d'ajouter -v ou --volumes, ce qui supprimerait les volumes nommés gérés par Compose. La documentation de compose down de Docker détaille ce comportement.

docker compose down

Définissez une variable shell avec le nom exact du volume que vous avez confirmé, puis extrayez l'archive à l'aide d'un conteneur temporaire. Cet exemple utilise l'image officielle alpine, monte le dossier de sauvegarde en lecture seule et monte le volume cible sur /restore. Remplacez myproject_db-data si votre nom réel est différent. L'image doit être disponible localement ou Docker doit être en mesure de la télécharger (pull).

VOLUME_NAME='myproject_db-data'
BACKUP_DIR="$HOME/backup-files"

docker run --rm \
  --mount "type=volume,source=$VOLUME_NAME,target=/restore" \
  --mount "type=bind,source=$BACKUP_DIR,target=/backup,readonly" \
  alpine sh -c 'cd /restore && tar -xf /backup/backup.tar --strip-components=1'

Cette commande suppose que l'archive comporte un niveau de répertoire englobant, par exemple data/file.db. Si le listage de l'archive a montré des fichiers directement à sa racine, supprimez --strip-components=1. Si les chemins ont un préfixe commun différent, choisissez le nombre de composants à supprimer pour que les fichiers attendus par l'application arrivent directement sous /restore. La syntaxe --mount rattache explicitement un volume nommé et un répertoire hôte ; Docker documente ces options de montage et le modèle de restauration dans son guide des volumes.

L'extraction remplace les fichiers ayant des chemins correspondants mais ne supprime pas les fichiers non liés déjà présents dans le volume. Si vous avez besoin d'une réplique exacte de la sauvegarde, une extraction de type fusion est insuffisante : effectuez d'abord une sauvegarde distincte du volume actuel, puis utilisez une procédure de nettoyage délibérée après avoir confirmé l'archive et la cible. N'exécutez pas de commande de suppression globale sur un volume que vous n'avez pas identifié.

Démarrer le projet et vérifier le résultat

Démarrez à nouveau les services Compose :

docker compose up -d

Compose réutilise un volume existant déclaré dans le projet, ou en crée un s'il est manquant. La référence des volumes Compose documente ce comportement. Vérifiez les journaux du service et, le cas échéant, utilisez les contrôles d'intégrité ou de récupération de base de données propres à l'application. Confirmez que les enregistrements ou fichiers attendus sont présents avant de considérer la restauration comme terminée.

Si le service signale un répertoire de données vide, revérifiez le nom du volume, le chemin du répertoire hôte et la structure de répertoires de l'archive. Vérifiez également que l'archive est compatible avec la version de l'application et que sa sauvegarde a été effectuée dans un état à partir duquel l'application peut récupérer ses données. Une extraction tar réussie confirme uniquement que les fichiers ont été décompressés ; elle ne garantit pas que les données de l'application sont valides.

Sources