Cómo solucionar Docker Permission Denied en un VPS (2026): docker.sock, grupos de usuarios y permisos de bind mount

Si ejecutas:

docker ps

y ves:

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

es un problema de permisos del usuario del host al acceder al daemon de Docker.

Si ves esto en los logs del contenedor o al operar la aplicación:

Permission denied: '/data/cache'
open /app/storage/logs/app.log: permission denied

normalmente es el usuario del contenedor el que no puede escribir en el directorio montado del host.

Primero distingue estas dos capas y luego actúa.

Antes de mirar los permisos, confirma primero que Docker no está caído:

systemctl status docker

Si el servicio no está iniciado:

sudo systemctl enable --now docker

Luego mira el archivo del socket:

ls -l /var/run/docker.sock

Salida habitual:

srw-rw---- 1 root docker 0 May 25 10:00 /var/run/docker.sock

La clave aquí es: el socket pertenece a root:docker y los permisos suelen ser 660. Es decir, root y los miembros del grupo docker pueden acceder a él.

Si el propio servicio de Docker es anómalo, no te apresures a cambiar permisos. Puedes revisar:

journalctl -u docker --since "30 minutes ago"

Si aún no estás familiarizado con los logs del sistema, puedes leer primero: Cómo leer los logs de un VPS: journalctl, systemctl, Nginx, logs de aplicaciones.

Consulta los grupos a los que pertenece el usuario actual:

id

Si no aparece docker, añade el usuario actual:

sudo usermod -aG docker $USER

Si estás dando permisos a otro usuario:

sudo usermod -aG docker deploy

Ojo: -aG no puede faltar. -G docker elimina al usuario de otros grupos suplementarios, lo que puede causar nuevos problemas de permisos.

Después de añadir el grupo, no lo juzgues como fallo de inmediato. La información de grupos de la sesión SSH actual no se refresca automáticamente.

Mucha gente ejecuta:

sudo usermod -aG docker $USER

y de inmediato ejecuta:

docker ps

y sigue recibiendo permission denied, así que piensa que el comando no sirvió. En realidad necesitas volver a iniciar sesión, o refrescar los grupos temporalmente:

newgrp docker

Y luego vuelve a probar:

docker ps

La forma más fiable es salir de SSH y volver a entrar:

exit

Tras reconectar, ejecuta:

id
docker ps

Si id ya contiene docker pero sigues sin permisos, continúa revisando si los permisos del socket se han roto.

Algunos tutoriales te dicen que ejecutes:

sudo chmod 777 /var/run/docker.sock

No lo hagas.

Poder acceder al socket de Docker equivale básicamente a obtener privilegios de root en el host. Porque un usuario puede iniciar un contenedor que monte el directorio raíz del host y luego modificar archivos del host.

Por ejemplo:

docker run --rm -it -v /:/host debian:12 chroot /host bash

Por eso, unirse al grupo docker es en sí mismo una operación de alto privilegio. Es más sensible que el simple "puede ejecutar contenedores". En producción, no añadas a la ligera usuarios de negocio, usuarios web y usuarios de CI al grupo docker.

Si has estropeado los permisos del socket, puedes reiniciar Docker primero para que restaure los valores por defecto:

sudo systemctl restart docker
ls -l /var/run/docker.sock

Si sigue anómalo, revisa el socket de systemd o la configuración del paquete de la distribución; no lo fuerces con 777.

Si:

sudo docker ps

funciona, pero:

docker ps

no funciona, significa que el daemon de Docker está bien y el problema son los permisos del usuario actual.

En este caso, no escribas todos los comandos de Docker con sudo docker ... de forma permanente. Para un VPS personal también sirve, pero tiene dos efectos secundarios:

• Los archivos generados pueden quedar como propiedad de root.
• Los permisos de los posteriores Compose, CI y scripts de despliegue serán más caóticos.

Se recomienda más bien: aclara qué usuario se encarga del despliegue, añádelo al grupo docker y ejecuta Docker con ese usuario.

Si instalaste rootless Docker, el socket no está necesariamente en:

/var/run/docker.sock

sino que puede estar en:

/run/user/1000/docker.sock

Comprueba las variables de entorno:

echo $DOCKER_HOST

Configuración habitual de rootless Docker:

export DOCKER_HOST=unix:///run/user/1000/docker.sock

Si llamas a Docker en un servicio systemd, cron o script de CI, el DOCKER_HOST de un shell interactivo puede no existir. En el script debes configurarlo explícitamente, o usar el entorno del usuario correcto.

Este tipo de problema también se mezcla a menudo con las tareas programadas. Si Docker se ejecuta manualmente en cron pero falla al ejecutarse automáticamente, puedes consultar: Qué hacer cuando las tareas programadas del VPS no se ejecutan.

Otro problema habitual es que el contenedor arranca correctamente pero la aplicación falla al escribir archivos.

Por ejemplo, en Compose:

services:
  app:
    image: my-app
    volumes:
      - ./data:/app/data

La aplicación dentro del contenedor da error al escribir en /app/data. En ese momento, mira primero los permisos del directorio del host:

ls -ld ./data
stat ./data

Luego mira con qué usuario se ejecuta realmente el proceso del contenedor:

docker exec -it app id
ps aux

Si el usuario dentro del contenedor es el UID 1000, y el directorio del host pertenece a root y no tiene permiso de escritura, fallará.

Puedes cambiar la propiedad del directorio al UID/GID correspondiente:

sudo chown -R 1000:1000 ./data

O especificar el usuario de ejecución en Compose:

services:
  app:
    image: my-app
    user: "1000:1000"
    volumes:
      - ./data:/app/data

No empieces con:

chmod -R 777 ./data

Esto permite que cualquier usuario local escriba, y el límite de seguridad es demasiado amplio.

Las bases de datos, los directorios que simulan almacenamiento de objetos y los directorios de subida web son los más propensos a romperse por problemas de permisos.

Por ejemplo, el directorio de datos de un contenedor MySQL debe ser escribible por el usuario mysql dentro del contenedor. Si montas un directorio propiedad de root, el contenedor puede fallar directamente al arrancar, o dejar archivos erróneos tras inicializarse a medias.

Orden de diagnóstico:

docker logs mysql
ls -ld ./mysql-data
docker exec -it mysql id mysql

Si es una aplicación web, como Laravel, WordPress o Nextcloud, normalmente hay que confirmar:

• Que los directorios storage / uploads / cache son escribibles.
• Si los UID/GID de Nginx/PHP-FPM/los contenedores de la aplicación coinciden.
• Si el script de copia de seguridad del host restaura los archivos como propiedad de root.

Si te encuentras con un 502/504 web y además hay errores de permisos en los logs, puedes comparar con: Qué hacer cuando un VPS muestra 502 / 504 Bad Gateway.

Muchos tutoriales de CI/CD escriben:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Así el runner de CI dentro del contenedor puede controlar el Docker del host. Pero el riesgo también es alto: si la tarea de CI es controlada por código malicioso, el atacante puede controlar el Docker del host y obtener además privilegios en el host.

El enfoque más fiable depende del escenario:

• VPS personal pequeño: se puede usar temporalmente, pero solo para proyectos de confianza.
• Equipos con varias personas: aísla el runner de CI en una máquina separada.
• Requisitos de alta seguridad: usa rootless Docker, constructores remotos o un entorno de compilación dedicado.

No expongas el socket de Docker a contenedores de aplicaciones web públicas.

Cuando encuentres Docker permission denied, revisa en este orden:

1. systemctl status docker para confirmar que el daemon de Docker está bien.
2. ls -l /var/run/docker.sock para ver el propietario y los permisos del socket.
3. id para ver si el usuario actual está en el grupo docker.
4. sudo usermod -aG docker $USER para añadir el grupo de usuarios.
5. Sal de SSH y vuelve a entrar, o ejecuta newgrp docker.
6. No hagas chmod 777 /var/run/docker.sock.
7. Si es rootless Docker, revisa DOCKER_HOST y /run/user/UID/docker.sock.
8. Si falla la escritura en un bind mount, revisa el propietario del directorio del host y el UID/GID dentro del contenedor.
9. Usa chown UID:GID o Compose user: para alinear los permisos.
10. En escenarios de CI/CD, monta /var/run/docker.sock con cuidado.

El Permission denied de Docker hay que separarlo primero por capas: ¿es el usuario del host al que se le deniega el acceso al socket de Docker, o es el proceso dentro del contenedor al que se le deniega escribir en un directorio montado?

Lo primero se suele resolver con el grupo de usuarios docker y volviendo a iniciar sesión; lo segundo requiere alinear el UID/GID del directorio del host y del usuario del contenedor. Lo que realmente no deberías hacer es un chmod 777 a lo bruto, especialmente /var/run/docker.sock. Los permisos del socket de Docker son esencialmente cercanos a los privilegios de root; a quien le das acceso, le estás confiando el control de este VPS.