Docker (et Portainer) : regrouper les données

Article de la série « Mon ordinateur Ubuntu »

J’ai expliqué dans des articles précédents comment j’ai installé des logiciels sous forme de containers Docker sur mon ordinateur Linux. Je veux maintenant pouvoir les sauvegarder automatiquement dans le cloud. Pour cela, il faut d’abord que je sache où sont stockés les fichiers essentiels — et surtout que je les regroupe tous au même endroit..

Pourquoi regrouper les données ?

Si on voit les containers comme des maisons, le fichier YAML (docker-compose.yml) est le plan de construction, mais il ne contient pas les habitants ni les meubles. Pour chaque container, il faut pouvoir localiser :

• Le docker-compose.yml : c’est le plan de l’architecte. Si la maison brûle, le plan permet de reconstruire exactement la même structure.
• Les volumes (les dossiers sur le Beelink) : ce sont tes meubles, tes photos et tes souvenirs. Si tu reconstruis la maison avec le plan mais que tu n’as plus tes meubles, la maison est vide.

Pour Stirling PDF ce n’est pas très grave de perdre les volumes car rien n’y est stocké de façon critique. Mais pour Portainer, ce serait une catastrophe : le fichier YAML réinstallera le logiciel, mais tu perdras toutes tes stacks, l’historique de tes containers et tes réglages utilisateurs.

L’objectif est donc de tout regrouper dans /home/USER/docker/nom-du-logiciel/ : le docker-compose.yml ET les dossiers de données, pour pouvoir tout sauvegarder d’un seul coup.

Pour toute nouvelle installation, suis la checklist PDF qui résume les 4 étapes à suivre avant de cliquer sur Deploy. Cet article explique comment corriger des installations existantes qui n’ont pas suivi cette discipline dès le départ.

Comment contraindre Docker à utiliser un répertoire spécifique ?

Par défaut, quand on utilise des « named volumes » dans le YAML, Docker stocke les données dans un dossier système caché et protégé – invisible depuis Portainer et inaccessible facilement. Il faut remplacer ces named volumes par des chemins absolus pointant vers ton dossier personnel.

La procédure est différente selon que le container est nouveau ou qu’il tourne déjà.

Cas 1 – Nouveau container (pas encore installé)

Étape 1 – Identifier les volumes dans la documentation

Va sur la page Docker Hub du logiciel et cherche la section « Volumes » ou « Mounts ». Elle liste les chemins internes du container – ce sont eux que tu vas « brancher » sur ton Beelink. Note-les avant de créer la stack.

Étape 2 – Créer les dossiers sur le Beelink

mkdir -p /home/USER/docker/nom-du-logiciel/sous-dossier1
mkdir -p /home/USER/docker/nom-du-logiciel/sous-dossier2

Tu Tu crées autant de dossiers que de volumes nécessaires. Et tu choisis librement leurs noms. Ce qui compte c’est que le YAML pointe ensuite vers ces mêmes dossiers.

Étape 3 – Écrire le YAML directement avec les chemins absolus

Dans l’éditeur de Stack Portainer, écris les volumes avec les chemins complets dès le départ :

volumes:
  - /home/USER/docker/nom-du-logiciel/sous-dossier1:/chemin/interne1
  - /home/USER/docker/nom-du-logiciel/sous-dossier2:/chemin/interne2

Pas de named volumes, pas de section volumes: en bas du fichier. Clique sur Deploy the stack.

Cas 2 – Container existant avec des named volumes

C’est la situation dans laquelle je me trouvais avec Stirling PDF et Nginx Proxy Manager – installés avant que je connaisse cette bonne pratique.

Étape 1 – Lire le YAML dans Portainer

Va dans Portainer – Stacks – nom de la stack – Editor. Tu vois quelque chose comme :

volumes:
  - stirling_trainingData:/usr/share/tesseract-ocr/5/tessdata
  - stirling_extraConfigs:/configs
  - stirling_customFiles:/customFiles
  - stirling_logs:/logs

Chaque ligne te donne deux informations :

• à gauche du : : le nom du named volume (ex: stirling_trainingData)
• à droite du : : le chemin interne du container (ex: /usr/share/tesseract-ocr/5/tessdata)

Étape 2 – Localiser les données sur le disque

Les named volumes sont stockés dans /var/lib/docker/volumes/. Le chemin complet se construit selon cette règle :

/var/lib/docker/volumes/ + [nom de la stack] + "_" + [nom du volume] + /_data/.

Pour vérifier les noms exacts avant de copier :

sudo ls /var/lib/docker/volumes/ | grep nom-de-la-stack

Pour Stirling PDF (stack nommée stirling-pdf), la correspondance est la suivante :

Tu choisis librement les noms des dossiers locaux – ce qui compte c’est la cohérence avec ce que tu écriras dans le YAML à l’étape 4.

Étape 3 – Créer les dossiers et migrer les données

Crée les dossiers de destination :

mkdir -p /home/USER/docker/stirling-pdf/{trainingData,configs,customFiles,logs}

Arrête le container depuis Portainer (Stop), puis copie les données :

# Le /. à la fin copie le contenu du dossier, pas le dossier lui-même
sudo cp -r /var/lib/docker/volumes/stirling-pdf_stirling_trainingData/_data/. /home/USER/docker/stirling-pdf/trainingData/
sudo cp -r /var/lib/docker/volumes/stirling-pdf_stirling_extraConfigs/_data/. /home/USER/docker/stirling-pdf/configs/
sudo cp -r /var/lib/docker/volumes/stirling-pdf_stirling_customFiles/_data/. /home/USER/docker/stirling-pdf/customFiles/
sudo cp -r /var/lib/docker/volumes/stirling-pdf_stirling_logs/_data/. /home/USER/docker/stirling-pdf/logs/

# Redonne les droits à ton utilisateur
sudo chown -R USER:USER /home/USER/docker/stirling-pdf

Étape 4 – Modifier le YAML dans Portainer

Dans l’éditeur de Stack, remplace les named volumes par les chemins absolus :

volumes:
  - /home/USER/docker/stirling-pdf/trainingData:/usr/share/tesseract-ocr/5/tessdata
  - /home/USER/docker/stirling-pdf/configs:/configs
  - /home/USER/docker/stirling-pdf/customFiles:/customFiles
  - /home/USER/docker/stirling-pdf/logs:/logs

Supprime la section volumes: en bas du fichier (celle qui listait les noms). Puis clique sur Update the stack.

Pourquoi le chemin complet plutôt que ./ ? Portainer stocke ses fichiers de manière un peu invisible. En écrivant le chemin entier, tu es certain à 100 % de l’endroit où les données atterrissent sur le disque – indispensable pour tes futures sauvegardes.

Cas particulier – Nginx Proxy Manager et les certificats Let’s Encrypt

NPM est indispensable à relocaliser car c’est là que se trouvent tes certificats Let’s Encrypt et toute ta configuration de proxy.

Sa structure de dossiers est la suivante :

nginx-proxy-manager/
├── data/           - base de données, logs, configuration nginx
└── letsencrypt/    - certificats SSL
    ├── archive/    - les vrais fichiers .pem
    ├── live/       - liens symboliques vers archive/
    └── renewal/    - configuration de renouvellement

Point d’attention important : le dossier letsencrypt/live/ ne contient pas de vrais fichiers mais des liens symboliques (symlinks) qui pointent vers les fichiers dans letsencrypt/archive/. Les deux dossiers doivent être présents dans ta sauvegarde pour que la restauration fonctionne. L’outil de sauvegarde Rclone doit être configuré avec l’option --links pour les copier correctement – c’est détaillé dans l’article sur la sauvegarde automatique.

La procédure de relocalisation est identique au Cas 2, avec ces volumes dans le YAML :

volumes:
  - /home/USER/docker/nginx-proxy-manager/data:/data
  - /home/USER/docker/nginx-proxy-manager/letsencrypt:/etc/letsencrypt

Créer le fichier docker-compose.yml

Une fois le container configuré et fonctionnel, crée immédiatement un fichier docker-compose.yml dans son dossier. Ce fichier est indispensable pour pouvoir reconstruire le container depuis zéro en cas de problème – et pour que la sauvegarde automatique soit complète.

nano /home/USER/docker/nom-du-logiciel/docker-compose.yml

Colle le contenu exact du YAML visible dans Portainer (Stacks – nom de la stack – Editor). Puis donne les bons droits :

sudo chown USER:USER /home/USER/docker/nom-du-logiciel/docker-compose.yml

Le chown est important : il permet au script de sauvegarde de mettre à jour ce fichier automatiquement à chaque sauvegarde, si tu modifies la stack dans Portainer.

Le script de sauvegarde vérifie à chaque lancement que ce fichier existe dans chaque dossier. Si ce n’est pas le cas, il écrit une ligne ATTENTION dans le log – un rappel quotidien jusqu’à ce que ce soit fait.

Cas particulier – Portainer

Portainer ne s’installe pas via une stack mais via une commande docker run directe – il n’apparaît donc pas dans la liste des stacks de Portainer et son YAML ne peut pas être exporté automatiquement. Crée son fichier manuellement :

nano /home/USER/docker/portainer/docker-compose.yml

Colle le contenu de ta stack Portainer tel qu’il apparaît dans Portainer – Stacks – Editor. Puis donne les bons droits :

sudo chown USER:USER /home/USER/docker/portainer/docker-compose.yml

Note sur les droits des données Portainer : contrairement aux autres containers, les fichiers dans portainer/data/ doivent appartenir à root (Portainer les crée et les gère en root). Ne fais pas de chown USER sur ce sous-dossier – uniquement sur le docker-compose.yml.

Supprimer les volumes inutilisés

Une fois que tu as vérifié que tout fonctionne avec les nouveaux chemins, supprime les anciens named volumes pour libérer de l’espace disque :

sudo docker volume prune

Cette commande supprime tous les volumes qui ne sont attachés à aucun container (allumé ou éteint). Elle ne touche pas à ce qui est dans ton dossier personnel ni aux volumes actifs.

En résumé, ton nouveau réflexe

« Un nouveau container ? Un nouveau dossier dans /home/USER/docker/ et un chemin complet dans le YAML – plus un docker-compose.yml créé immédiatement. »

C’est cette discipline qui fera que, dans 6 mois, quand tu auras 10 logiciels différents, tu pourras tout sauvegarder sur ton Google Drive d’une seule traite, car tout sera sagement rangé au même endroit.

Dans le prochain article de cette série, nous verrons comment configurer Rclone pour sauvegarder automatiquement tout le dossier /home/USER/docker/ vers Google Drive.