Docker volumes : corriger les permissions en 3 commandes

Docker partage le noyau Linux de l'hôte. Il n'existe pas de couche de virtualisation des utilisateurs : chaque processus dans un conteneur possède un UID et un GID réels, visibles depuis l'hôte. Quand un conteneur monte un répertoire hôte (bind-mount), le système de fichiers ne fait aucune magie : il applique les mêmes règles de permissions POSIX que pour n'importe quel processus local. Un fichier appartenant à l'UID 1000 sur l'hôte reste la propriété de l'UID 1000, peu importe que ce soit un utilisateur qui s'appelle alice côté hôte ou paperless côté conteneur. Si le processus dans le conteneur tourne sous l'UID 472 et que le répertoire appartient à root (UID 0), l'écriture est refusée — même si vous avez utilisé chmod 755.

Pourquoi les images n'utilisent-elles pas root par défaut ? La majorité des images Docker bien maintenues créent un utilisateur applicatif dédié pour respecter le principe de moindre privilège : un processus compromis ne peut pas modifier les binaires système du conteneur ni, si les options de sécurité sont correctes, accéder aux fichiers root de l'hôte. C'est une bonne pratique — mais elle introduit précisément ce décalage d'UID.

Le piège classique : vous créez le répertoire avec votre session SSH (UID 1000), puis vous lancez un conteneur Grafana qui tourne en UID 472. Grafana tente d'écrire sa base SQLite dans /var/lib/grafana monté depuis /opt/grafana/data — qui appartient à votre utilisateur SSH. Résultat : GF_PATHS_DATA='/var/lib/grafana' is not writable. Le conteneur démarre, répond sur le port 3000, mais toute configuration est perdue au redémarrage suivant car rien n'a jamais été écrit sur le disque.

Les problèmes de permissions Docker touchent principalement les applications qui s'exécutent avec un UID spécifique différent de celui de l'hôte.

Avant de corriger, confirmez que c'est bien un problème de permissions et identifiez l'UID en cause. Trois commandes suffisent.

La correction de base est un chown du répertoire hôte vers l'UID attendu par le conteneur. Voici les commandes pour les applications les plus courantes.

Le chown sur le répertoire hôte fonctionne pour les bind-mounts, mais Docker propose trois autres approches selon le contexte et l'image utilisée.

Directive user: dans compose.yml. Certaines images sont conçues pour accepter un UID arbitraire passé via user:. Cela évite le chown si votre répertoire appartient à votre utilisateur hôte :

services:
  app:
    image: mon-image
    user: "1000:1000"
    volumes:
      - /home/user/data:/app/data

Cette approche fonctionne uniquement si l'image ne requiert pas de fichiers internes appartenant à un UID spécifique (binaires SUID, sockets, etc.). Paperless-ngx supporte ce mode via sa variable USERMAP_UID ; Grafana ne le supporte pas proprement car son image modifie des permissions lors de son entrypoint. Si vous forcez user: 472:472 sur Grafana, le conteneur échoue au démarrage avec des erreurs sur /var/lib/grafana.

Variables d'environnement PUID/PGID. Les images de la communauté LinuxServer.io exposent les variables PUID et PGID : l'entrypoint de l'image reçoit un processus root, change dynamiquement l'UID de l'utilisateur applicatif avec usermod/groupmod, puis descend de privilèges. C'est pratique mais ces variables sont propres aux images LinuxServer.io — elles n'ont aucun effet sur les images officielles de Grafana, Nextcloud ou Immich. Ne les mélangez pas.

Volumes nommés. Avec un volume Docker nommé (docker volume create), Docker gère lui-même le répertoire sous /var/lib/docker/volumes/. À la première écriture, le répertoire est créé avec les permissions du processus du conteneur. Résultat : pas de problème de permissions au démarrage, mais la migration des données existantes nécessite une étape de copie explicite :

docker run --rm \
  -v mon-ancien-repertoire:/from \
  -v mon-volume-nomme:/to \
  alpine sh -c 'cp -a /from/. /to/'

Les volumes nommés conviennent bien aux nouvelles installations ; pour les données existantes, le bind-mount avec un chown préalable reste plus prévisible.

Les montages NFS et CIFS (partages Samba/Windows) ajoutent une couche de complexité car l'arbitrage des permissions se fait à deux endroits : le système de fichiers local ET le serveur distant. Comprendre lequel des deux bloque est essentiel avant de chercher une correction.

Problème NFS — root_squash. Par défaut, un serveur NFS exporte avec root_squash : tout accès qui arrive avec UID 0 (root) est automatiquement réattribué à l'utilisateur nobody (UID 65534). Si votre conteneur tourne en UID 472 et que le partage NFS n'a pas de mapping UID côté serveur, le client monte le partage, voit les fichiers, mais l'écriture est refusée — parce que le serveur NFS considère que l'UID 472 du client n'a pas les droits sur ce partage.

Solutions :
1. Configurer l'export NFS avec all_squash,anonuid=472,anongid=472 pour Grafana, ou l'UID correspondant à votre application.
2. Créer un utilisateur côté serveur NFS avec le même UID que dans le conteneur et lui attribuer la propriété des répertoires partagés.
3. Utiliser no_root_squash uniquement si vous contrôlez complètement le réseau interne — cette option permet à root sur le client d'agir comme root sur le serveur, ce qui est un risque de sécurité significatif.

Problème CIFS — options de montage figées. Contrairement à ext4 ou XFS, un montage CIFS ne supporte pas le chown après montage : la propriété est fixée par les options passées à la commande de montage. Si vous montez un partage Windows sans spécifier d'UID, les fichiers apparaissent en root (UID 0) et les conteneurs Nextcloud (UID 33) ne peuvent pas y écrire, quelle que soit la permission POSIX visible côté client.

Pour les montages CIFS dans /etc/fstab :

//serveur/partage /opt/nextcloud/data cifs uid=33,gid=33,credentials=/etc/cifs-creds,iocharset=utf8 0 0

Vérifiez toujours que le fichier de credentials (/etc/cifs-creds) n'est lisible que par root (chmod 600).

Voici les quatre erreurs Docker les plus courantes liées aux permissions, avec le message d'erreur exact et sa solution.

Le Permission denied dans les logs Docker n'est jamais une fatalité. La solution tient en trois commandes : docker exec <conteneur> id pour connaître l'UID, ls -ln <répertoire-hôte> pour confirmer le propriétaire actuel, puis chown -R <UID>:<GID> <répertoire-hôte> pour corriger. La règle d'or : créer les répertoires hôtes avec le bon propriétaire avant de démarrer le conteneur, pas après.

Pour éviter de reproduire le problème à chaque nouvelle installation, documentez les UIDs dans votre compose.yml sous forme de commentaires et intégrez le chown dans votre script de provisionnement ou votre playbook Ansible. Un rôle Ansible qui crée les répertoires de données avec owner: 472 et group: 472 (pour Grafana) avant le docker compose up élimine la cause à la racine.

Sur un VPS dédié, cette discipline évite 90 % des incidents de données silencieusement perdues au redémarrage — des incidents qui ne produisent aucune alerte car le conteneur est vert, le service répond, mais tout ce qui a été configuré depuis le dernier démarrage a disparu. Un chown de deux secondes avant le premier lancement vous en épargne des heures de débogage.