Permisos de volúmenes Docker: corrección en 3 comandos

El mecanismo: por qué Docker se niega a escribir

Las aplicaciones más afectadas y sus UIDs

• Paperless-ngx — UID 1000 (usuario paperless): gestiona los directorios consume, export, media y data
• Grafana — UID 472 (usuario grafana): escribe su base SQLite y plugins en /var/lib/grafana
• Nextcloud (imagen Debian) — UID 33 (usuario www-data): directorio de datos, config y logs
• Immich — UID 1000 (usuario node): librería de fotos, miniaturas y base de datos ML
• Gitea — UID 1000 (usuario git): repositorios, claves SSH, logs y base SQLite por defecto

Diagnóstico: identificar el problema en menos de 2 minutos

1. 01

   Leer el mensaje de error exacto

   Consulta los logs del contenedor afectado:

   docker logs <nombre-contenedor> 2>&1 | grep -i 'permission\|denied\|cannot\|mkdir'

   Un mensaje permission denied o cannot create directory confirma el diagnóstico.

2. 02

   Identificar el UID del proceso dentro del contenedor

   docker exec <nombre-contenedor> id

   Salida típica: uid=472(grafana) gid=0(root). Apunta el UID — aquí 472.

3. 03

   Verificar el propietario del directorio en el host

   ls -ln /opt/grafana/data

   Salida drwxr-xr-x 2 0 0 ... indica que el directorio pertenece a root (UID 0). El UID 472 solo tiene derechos «other» — lectura y ejecución, sin escritura.

4. 04

   Usar stat para un diagnóstico completo

   stat /opt/grafana/data

   Revisa las líneas Uid: y Gid:. Si muestran (0/root) mientras tu contenedor corre como 472, el problema está confirmado.

5. 05

   Inspeccionar la configuración del contenedor

   docker inspect <nombre-contenedor> | grep -A5 'Mounts'

   Este comando lista todos los bind-mounts y volúmenes nombrados activos.

Corrección caso por caso: chown en el directorio del host

1. 06

   Grafana (UID 472)

   mkdir -p /opt/grafana/data
   chown -R 472:472 /opt/grafana/data

   En tu compose.yml:

   volumes:
     - /opt/grafana/data:/var/lib/grafana

2. 07

   Nextcloud (UID 33, imagen Debian)

   mkdir -p /opt/nextcloud/{data,config,apps}
   chown -R 33:33 /opt/nextcloud/data
   chown -R 33:33 /opt/nextcloud/config

   Nota: la imagen Alpine usa UID 82. Verifica con docker exec <contenedor> id www-data si no estás seguro de la variante.

3. 08

   Paperless-ngx (UID 1000)

   mkdir -p /opt/paperless/{consume,export,media,data}
   chown -R 1000:1000 /opt/paperless/consume
   chown -R 1000:1000 /opt/paperless/export
   chown -R 1000:1000 /opt/paperless/media
   chown -R 1000:1000 /opt/paperless/data

4. 09

   Immich (UID 1000)

   mkdir -p /opt/immich/{library,thumbnails,encoded-video,profile}
   chown -R 1000:1000 /opt/immich

   Nota: las variables de entorno PUID/PGID NO funcionan con las imágenes oficiales de Immich.

5. 10

   Verificar tras la corrección

   ls -ln /opt/grafana/data

   Debe mostrar drwxr-xr-x 2 472 472 .... Luego reinicia el contenedor:

   docker compose restart grafana
   docker logs grafana --tail 20

Variantes: bind-mounts, volúmenes nombrados y user:

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

Casos NFS y montajes remotos

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

Métodos de corrección: comparación

Desplace la tabla

Resolución de problemas: 4 errores clásicos con su mensaje exacto

• mkdir: cannot create directory '/var/lib/grafana/plugins': Permission denied → El directorio del host no pertenece al UID 472. Aplica chown -R 472:472 /opt/grafana/data.
• [Errno 13] Permission denied: '/usr/src/paperless/media' → Paperless-ngx no puede escribir en su directorio media. Verifica que el bind-mount pertenece al UID 1000 en el host.
• Could not create lock file /var/lib/grafana/.~lock.grafana.db → Grafana puede leer el directorio pero no escribir. Problema de permisos en archivos existentes: chown 472:472 /opt/grafana/data/*.db o elimina el lock file.
• chown: changing ownership of '/data': Operation not permitted (al arrancar el contenedor) → La imagen intenta corregir permisos pero no puede porque no corre como root. Ejecuta el chown manualmente en el host ANTES de arrancar el contenedor.

Conclusión