Como Resolver o Erro Docker “Got permission denied while trying to connect to the Docker daemon socket” [Guia Atualizado 2026]

スポンサーリンク

Como Resolver o Erro Docker “Got permission denied while trying to connect to the Docker daemon socket” [Guia Atualizado 2026]

Um dos erros mais comuns ao começar a usar o Docker é “Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock”. Este artigo explica detalhadamente as causas e soluções específicas para este erro, atualizado para os ambientes mais recentes de 2026. É uma leitura essencial para todos os usuários que executam Docker no Linux (Ubuntu, CentOS, Debian, etc.).

O Que É Este Erro? Sintomas Que Você Vai Experimentar

Após instalar o Docker ou ao executar comandos docker em um servidor Linux, você pode ver a seguinte mensagem de erro:

docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/create": dial unix /var/run/docker.sock: connect: permission denied.

Este erro pode ocorrer com praticamente qualquer comando Docker, incluindo docker ps, docker run e docker-compose up. Especificamente, você pode encontrar os seguintes sintomas:

  • docker run hello-world falha: O caso mais comum ao verificar a instalação do Docker
  • docker ps não mostra os containers: Não é possível ver containers em execução devido a erros de permissão
  • docker-compose up não inicia: Aplicações multi-container falham ao iniciar
  • Pipelines CI/CD falham: Comandos Docker no Jenkins, GitHub Actions, GitLab CI, etc. param com erros de permissão
  • Extensão Dev Containers do VS Code não consegue conectar: Não é possível conectar ao Docker em ambientes de desenvolvimento remoto

Quando este erro ocorre, toda a funcionalidade do Docker fica inutilizável, parando completamente seu trabalho de desenvolvimento. Isso é particularmente frustrante para usuários que estão começando com o Docker.

Causas Deste Erro

Causa 1: O Usuário Atual Não Está no Grupo Docker

Esta é a causa mais comum. O daemon Docker se comunica por padrão através de um socket Unix (/var/run/docker.sock), e este socket pertence ao usuário root (administrador). Usuários regulares precisam pertencer ao grupo docker para executar comandos Docker. Simplesmente instalar o Docker não adiciona automaticamente seu usuário a este grupo, resultando em erros de permissão.

# Verificar permissões do socket
ls -la /var/run/docker.sock
# Saída exemplo: srw-rw---- 1 root docker 0 Feb 12 10:00 /var/run/docker.sock

Causa 2: Não Fez Logout/Login Após Mudança de Grupo

Após executar sudo usermod -aG docker $USER para adicionar seu usuário ao grupo docker, você não fez logout e login novamente. No Linux, mudanças na associação a grupos não entram em vigor até que você inicie uma nova sessão (login). Este é um descuido muito comum, e perguntas como “executei o comando mas ainda não funciona” aparecem frequentemente no Stack Overflow e Reddit.

Causa 3: O Daemon Docker Não Está Em Execução

Um erro similar pode ocorrer quando o serviço Docker está parado. Isso acontece quando o Docker não está configurado para iniciar automaticamente após reiniciar o servidor, ou quando a instalação do Docker está incompleta.

# Verificar status do serviço Docker
sudo systemctl status docker

Causa 4: Permissões do /var/run/docker.sock Foram Modificadas Incorretamente

Isso ocorre quando as permissões do arquivo do socket foram alteradas manualmente, ou quando ferramentas de segurança redefiniram as permissões. O socket deveria ser srw-rw---- com propriedade root:docker; se as permissões forem diferentes, conexões normais falharão.

Causa 5: Restrições de Acesso do SELinux ou AppArmor

Em distribuições Linux com segurança reforçada (RHEL, CentOS, Fedora, etc.), o SELinux pode bloquear o acesso ao socket Docker. Da mesma forma, no Ubuntu e sistemas similares, o AppArmor pode ser a causa.

Solução 1: Adicionar Seu Usuário ao Grupo Docker (Recomendada)

Esta é a solução mais segura e recomendada. É também a abordagem recomendada na documentação oficial do Docker.

Passo 1: Verificar Se o Grupo Docker Existe

Primeiro, verifique se o grupo docker existe no seu sistema. Normalmente é criado automaticamente durante a instalação do Docker, mas vale a pena conferir.

# Verificar se o grupo docker existe
cat /etc/group | grep docker

Se o grupo não existir, crie-o com o seguinte comando:

# Criar o grupo docker
sudo groupadd docker

Passo 2: Adicionar o Usuário Atual ao Grupo Docker

Use o seguinte comando para adicionar o usuário logado ao grupo docker:

# Adicionar usuário atual ao grupo docker
sudo usermod -aG docker $USER

Explicação do comando:
– usermod: Comando para modificar contas de usuário
– -a: Modo de adição (não remove de grupos existentes)
– -G docker: Especifica o grupo docker
– $USER: Preenchido automaticamente com o nome do usuário logado

Para adicionar um usuário específico, substitua $USER pelo nome de usuário:

# Exemplo: Adicionar um usuário específico
sudo usermod -aG docker nomeusuario

Passo 3: Aplicar a Mudança de Grupo

Método A: Fazer logout e login novamente (mais confiável)

# Para conexões SSH
exit
# Depois reconectar via SSH

# Para ambientes desktop
# Fazer logout e login novamente

Método B: Usar newgrp para efeito imediato (apenas terminal atual)

# Ativar imediatamente o grupo docker na sessão do shell atual
newgrp docker

Este método só funciona para a sessão do terminal atual. Ao abrir novos terminais, você precisará fazer logout e login novamente.

Passo 4: Verificar a Configuração

# Verificar se você pertence ao grupo docker
groups

# Testar se o Docker funciona corretamente
docker run hello-world

Se aparecer a mensagem Hello from Docker!, a configuração foi concluída com sucesso.

Notas Importantes

  • Esquecer a opção -a (append) fará com que o usuário pertença “apenas” ao grupo docker, removendo-o de todos os outros grupos. Sempre use -aG juntos
  • Pertencer ao grupo docker concede privilégios equivalentes a root ao usuário. Adicione apenas usuários confiáveis
  • Em ambientes WSL2 (Windows Subsystem for Linux), reiniciar o WSL (wsl --shutdown) pode ser necessário

Solução 2: Usar sudo com Comandos Docker

Esta é uma alternativa para ambientes onde você não pode alterar configurações de grupo, ou quando precisa usar o Docker temporariamente.

Simplesmente adicione sudo antes de todos os comandos Docker para executá-los com privilégios de root:

# Executar comandos Docker com sudo
sudo docker run hello-world
sudo docker ps
sudo docker-compose up -d

Este método funciona imediatamente mas tem as seguintes desvantagens:

  • Requer digitar sudo toda vez
  • Torna a execução dentro do Docker Compose e scripts trabalhosa
  • sudo pode não estar disponível em pipelines CI/CD
  • Variáveis de ambiente e configurações de contexto Docker usam as do usuário root

Para uso a longo prazo, adicionar seu usuário ao grupo docker (Solução 1) é fortemente recomendado.

Para uso com Docker Compose:

# Docker Compose
sudo docker compose up -d

# Docker Compose legado (v1)
sudo docker-compose up -d

Solução 3: Usar o Modo Rootless do Docker (Avançado)

O modo Rootless, oficialmente suportado desde o Docker 20.10, executa o daemon Docker com privilégios de usuário regular. Em 2026, o Docker Engine 27.x melhorou ainda mais a estabilidade, tornando-o a abordagem recomendada para ambientes de produção que priorizam a segurança.

Benefícios do Modo Rootless

  • Nenhum privilégio root necessário
  • Riscos de segurança significativamente reduzidos
  • Menor risco de comprometimento do host a partir dos containers

Passos de Instalação

Primeiro, instale os pacotes de dependência necessários:

# Ubuntu/Debian
sudo apt-get install -y uidmap dbus-user-session

# CentOS/RHEL
sudo yum install -y shadow-utils fuse-overlayfs

Em seguida, execute o script de configuração do modo Rootless:

# Parar Docker existente (rootful)
sudo systemctl disable --now docker.service docker.socket

# Instalar modo Rootless
dockerd-rootless-setuptool.sh install

Configure as variáveis de ambiente:

# Adicionar ao ~/.bashrc ou ~/.zshrc
export PATH=/usr/bin:$PATH
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock

# Aplicar configurações
source ~/.bashrc

# Verificar se funciona
docker run hello-world

Notas Importantes

  • O modo Rootless tem algumas limitações (bind de portas privilegiadas 80/443, certos drivers de armazenamento, etc.)
  • Imagens e volumes criados com privilégios root não podem ser usados diretamente
  • A configuração de rede pode diferir do modo padrão

Como Prevenir Este Erro

Tome as seguintes medidas preventivas para evitar erros de permissão do Docker.

1. Configure as Definições de Grupo Imediatamente Após a Instalação do Docker

Complete a adição ao grupo docker antes de executar seu primeiro comando após instalar o Docker. Inclua isso na sua documentação de setup ou scripts para um processo eficiente.

# Exemplo de script de configuração pós-instalação
#!/bin/bash
sudo groupadd docker 2>/dev/null
sudo usermod -aG docker $USER
echo "Por favor, faça logout e login novamente"

2. Automatize com Ansible ou Shell Scripts

Ao automatizar desenvolvimento em equipe ou construção de servidores, inclua a instalação do Docker e configuração de grupo nos seus scripts de automação.

3. Verifique as Configurações de Permissão do Pipeline CI/CD

Para GitHub Actions, GitLab CI, Jenkins, etc., verifique antecipadamente que as permissões de acesso ao socket Docker estão corretamente configuradas. Muitas plataformas CI/CD requerem configurações específicas para uso do Docker.

4. Verifique Regularmente o Status do Serviço Docker

# Habilitar auto-start do Docker
sudo systemctl enable docker

# Verificar status do serviço Docker
sudo systemctl status docker

5. Nunca Use chmod 666

Você pode encontrar chmod 666 /var/run/docker.sock sugerido como “solução” na internet, mas isso é extremamente perigoso do ponto de vista de segurança. Concede a todos os usuários acesso ao daemon Docker, efetivamente dando privilégios root a todos. Nunca use isso em ambientes de produção.

Resumo

O erro Docker “Got permission denied while trying to connect to the Docker daemon socket” é um erro extremamente comum encontrado por praticamente todos os usuários Linux que começam com Docker. No entanto, com a compreensão adequada de suas causas e soluções, pode ser resolvido em minutos.

Pontos-chave:
– Recomendado: Adicionar seu usuário ao grupo docker com sudo usermod -aG docker $USER e fazer logout & login novamente
– Temporário: Usar sudo docker para execução imediata de comandos
– Foco em segurança: Considerar o modo Rootless do Docker

Se o problema persistir, verifique o seguinte:
1. O serviço Docker está em execução? (sudo systemctl status docker)
2. As permissões do arquivo socket estão corretas? (ls -la /var/run/docker.sock)
3. As configurações do SELinux/AppArmor estão interferindo?

Se ainda não conseguir resolver, recomendamos perguntar nos fóruns da comunidade Docker ou Stack Overflow com detalhes do seu ambiente (SO, versão do Docker, mensagem de erro completa).

Referências

コメント

タイトルとURLをコピーしました