Como resolver Docker Permission Denied em uma VPS (2026): docker.sock, grupos de usuários e permissões de bind mount

Se você executa:

docker ps

e vê:

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

é um problema de permissão do usuário do host ao acessar o daemon do Docker.

Se você vê isto nos logs do contêiner ou ao operar a aplicação:

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

normalmente é o usuário dentro do contêiner que não consegue gravar no diretório montado do host.

Primeiro diferencie essas duas camadas e depois aja.

Antes de olhar as permissões, confirme primeiro que o próprio Docker não caiu:

systemctl status docker

Se o serviço não iniciou:

sudo systemctl enable --now docker

Depois olhe o arquivo do socket:

ls -l /var/run/docker.sock

Saída comum:

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

O ponto-chave aqui é: o socket pertence a root:docker e as permissões costumam ser 660. Ou seja, root e os membros do grupo docker podem acessá-lo.

Se o próprio serviço do Docker estiver anormal, não se apresse em alterar permissões. Você pode verificar:

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

Se você ainda não está familiarizado com logs do sistema, pode ler primeiro: Como ler os logs da VPS: journalctl, systemctl, Nginx, logs de aplicações.

Veja os grupos aos quais o usuário atual pertence:

id

Se docker não estiver lá, adicione o usuário atual:

sudo usermod -aG docker $USER

Se você está dando permissão a outro usuário:

sudo usermod -aG docker deploy

Atenção: -aG não pode faltar. -G docker remove o usuário de outros grupos suplementares, o que pode causar novos problemas de permissão.

Depois de adicionar o grupo, não julgue como falha imediatamente. As informações de grupo na sessão SSH atual não são atualizadas automaticamente.

Muitas pessoas executam:

sudo usermod -aG docker $USER

e logo em seguida executam:

docker ps

e ainda recebem permission denied, então acham que o comando não funcionou. Na verdade, você precisa fazer login novamente ou atualizar os grupos temporariamente:

newgrp docker

Depois tente de novo:

docker ps

A forma mais confiável é sair do SSH e entrar novamente:

exit

Após reconectar, execute:

id
docker ps

Se id já contém docker, mas você ainda não tem permissão, continue verificando se as permissões do socket foram alteradas de forma incorreta.

Alguns tutoriais mandam executar:

sudo chmod 777 /var/run/docker.sock

Não faça isso.

Poder acessar o socket do Docker é basicamente equivalente a obter privilégios de root no host. Porque o usuário pode iniciar um contêiner que monta o diretório raiz do host e depois modificar arquivos do host.

Por exemplo:

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

Portanto, entrar no grupo docker já é, por si só, uma operação de alto privilégio. É mais sensível do que o simples "consegue rodar contêineres". Em produção, não adicione de qualquer jeito usuários de negócio, usuários web e usuários de CI ao grupo docker.

Se você bagunçou as permissões do socket, pode primeiro reiniciar o Docker para que ele restaure o padrão:

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

Se ainda estiver anormal, verifique o socket do systemd ou a configuração do pacote da distribuição; não force a barra com 777.

Se:

sudo docker ps

funciona, mas:

docker ps

não funciona, significa que o daemon do Docker está normal e o problema são as permissões do usuário atual.

Nesse caso, não escreva todos os comandos do Docker com sudo docker ... permanentemente. Para uma VPS pessoal isso também funciona, mas traz dois efeitos colaterais:

• Os arquivos gerados podem ficar com proprietário root.
• As permissões dos posteriores Compose, CI e scripts de implantação ficarão mais confusas.

A recomendação melhor é: defina qual usuário é responsável pela implantação, adicione-o ao grupo docker e execute o Docker com esse usuário.

Se você instalou o rootless Docker, o socket não está necessariamente em:

/var/run/docker.sock

mas pode estar em:

/run/user/1000/docker.sock

Verifique as variáveis de ambiente:

echo $DOCKER_HOST

Configurações comuns do rootless Docker:

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

Se você chama o Docker em um serviço systemd, cron ou script de CI, o DOCKER_HOST de um shell interativo pode não existir. No script, defina explicitamente ou use o ambiente do usuário correto.

Esse tipo de problema também costuma se misturar com tarefas agendadas. Se o Docker funciona manualmente no cron mas falha ao executar automaticamente, consulte: O que fazer quando as tarefas agendadas da VPS não executam.

Outro problema comum é o contêiner iniciar com sucesso, mas a aplicação falhar ao gravar arquivos.

Por exemplo, no Compose:

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

A aplicação dentro do contêiner dá erro ao gravar em /app/data. Nesse momento, primeiro veja as permissões do diretório no host:

ls -ld ./data
stat ./data

Depois veja com qual usuário o processo do contêiner realmente roda:

docker exec -it app id
ps aux

Se o usuário dentro do contêiner for o UID 1000, e o diretório do host pertencer a root e não tiver permissão de gravação, vai falhar.

Você pode alterar a propriedade do diretório para o UID/GID correspondente:

sudo chown -R 1000:1000 ./data

Ou especificar o usuário de execução no Compose:

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

Não comece com:

chmod -R 777 ./data

Isso permite que qualquer usuário local grave, e o limite de segurança fica amplo demais.

Bancos de dados, diretórios que simulam armazenamento de objetos e diretórios de upload web são os mais facilmente prejudicados por problemas de permissão.

Por exemplo, o diretório de dados de um contêiner MySQL precisa ser gravável pelo usuário mysql dentro do contêiner. Se você montar um diretório com proprietário root, o contêiner pode falhar diretamente ao iniciar, ou deixar arquivos errados após inicializar pela metade.

Ordem de investigação:

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

Se for uma aplicação web, como Laravel, WordPress ou Nextcloud, normalmente é preciso confirmar:

• Se os diretórios storage / uploads / cache são graváveis.
• Se os UID/GID do Nginx/PHP-FPM/contêineres da aplicação são consistentes.
• Se o script de backup do host restaura os arquivos com proprietário root.

Se você encontrar 502/504 na web e também houver erros de permissão nos logs, pode comparar com: O que fazer quando a VPS apresenta 502 / 504 Bad Gateway.

Muitos tutoriais de CI/CD escrevem:

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

Assim, o runner de CI dentro do contêiner pode controlar o Docker do host. Mas o risco também é alto: se a tarefa de CI for controlada por código malicioso, o atacante poderá controlar o Docker do host e obter ainda mais privilégios no host.

A abordagem mais confiável depende do cenário:

• VPS pessoal pequena: pode ser usada temporariamente, mas apenas para projetos confiáveis.
• Equipes com várias pessoas: isole o runner de CI em uma máquina separada.
• Requisitos de alta segurança: use rootless Docker, builders remotos ou um ambiente de build dedicado.

Não exponha o socket do Docker a contêineres de aplicações web públicas.

Ao encontrar Docker permission denied, verifique nesta ordem:

1. systemctl status docker para confirmar que o daemon do Docker está normal.
2. ls -l /var/run/docker.sock para ver o proprietário e as permissões do socket.
3. id para ver se o usuário atual está no grupo docker.
4. sudo usermod -aG docker $USER para adicionar o grupo de usuários.
5. Saia do SSH e entre novamente, ou execute newgrp docker.
6. Não faça chmod 777 /var/run/docker.sock.
7. Se for rootless Docker, verifique DOCKER_HOST e /run/user/UID/docker.sock.
8. Se a gravação no bind mount falhar, verifique o proprietário do diretório no host e o UID/GID dentro do contêiner.
9. Use chown UID:GID ou Compose user: para alinhar as permissões.
10. Em cenários de CI/CD, monte /var/run/docker.sock com cuidado.

O Permission denied do Docker precisa primeiro ser separado por camadas: é o usuário do host tendo o acesso ao socket do Docker negado, ou é o processo dentro do contêiner tendo a gravação em um diretório montado negada?

O primeiro caso geralmente se resolve com o grupo de usuários docker e fazendo login novamente; o segundo exige alinhar o UID/GID do diretório do host e do usuário do contêiner. O que você realmente não deve fazer é um chmod 777 de uma vez, especialmente /var/run/docker.sock. As permissões do socket do Docker são essencialmente próximas dos privilégios de root; a quem você dá acesso, é a quem você confia o controle desta VPS.