Por que o Portainer não enxergou meu container rodando? Troubleshooting de comunicação com a Docker API e socket unix

O container rodava, mas o Portainer não via: caçada à comunicação com a Docker API#

Muitas vezes, ferramentas de interface gráfica usadas para gerenciar aplicações (como o Portainer) podem apresentar comportamentos inesperados. Recentemente, passei por uma situação curiosa: eu tinha um container ativo e rodando normalmente pelo terminal do servidor, mas ao abrir a interface web do Portainer no mesmo host, o container parecia invisível na listagem.

Se você já se perguntou "como adicionar um container já em execução ao Portainer se ambos estão na mesma máquina?", este artigo disseca a arquitetura interna do Docker, o comportamento do Portainer e como diagnosticar problemas de visibilidade na prática.

1. O cenário inicial#

No terminal do host, executei os comandos padrão para verificar o status dos processos:

docker ps

CONTAINER ID   IMAGE              COMMAND                  CREATED          STATUS          PORTS                                      NAMES
045839afd846   app-custom-image   "docker-entrypoint.s…"   13 minutes ago   Up 13 minutes   0.0.0.0:8889->3000/tcp, [::]:8889->3000/tcp   my-web-app

O container my-web-app (ID 045839afd846) estava ativo, saudável e respondendo na porta 8889. No entanto, ao abrir a interface gráfica do Portainer, surgiu a dúvida: o Portainer deveria listar o container automaticamente? Existe um botão para importar? Por que ele não aparece?

2. Como o Portainer se comunica com o Docker#

Para entender a causa, é preciso observar a arquitetura de comunicação:

1. O Portainer não possui um banco de dados próprio para o estado dos containers. Ele não guarda uma lista separada de processos.
2. O Portainer é um cliente HTTP da Docker Engine API. Toda vez que você abre a aba de containers, o Portainer faz requisições REST para o daemon do Docker (dockerd).
3. No Linux, essa comunicação ocorre prioritariamente via Unix Domain Socket (/var/run/docker.sock).

Quando a configuração está correta, o fluxo funciona assim:

• O Portainer executa a syscall connect() no socket /var/run/docker.sock.
• Envia a requisição GET /v1.41/containers/json?all=1.
• O dockerd responde com o JSON estruturado contendo todos os containers, incluindo o ID de my-web-app.

Portanto, não existe um botão "Importar Container". Qualquer container reconhecido pelo dockerd deve aparecer automaticamente, a menos que haja uma quebra de permissão, isolamento de rede ou filtro de exibição.

3. Principais causas de falha de visibilidade#

Ao analisar por que um container ativo no mesmo servidor pode não aparecer no painel, mapeei os pontos mais comuns:

A. Montagem ausente ou incorreta do socket unix#

Se o Portainer foi iniciado como um container Docker, ele precisa de acesso direto ao socket do host:

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

Se esse volume não foi montado, ou se o endpoint no Portainer (Settings > Environments) estiver configurado incorretamente para TCP (localhost:2375) sem que o daemon esteja escutando nessa porta de rede, o painel não receberá nenhum dado.

B. Permissões de arquivo no /var/run/docker.sock#

No host, o socket do Docker pertence ao usuário root:docker com permissões srw-rw----:

ls -la /var/run/docker.sock
# srw-rw---- 1 root docker 0 Aug 30 10:00 /var/run/docker.sock

Se o processo do Portainer rodar sob um UID sem permissão de leitura e escrita no grupo docker, a chamada open() retornará EACCES (Permission denied).

C. Filtros de RBAC e containers marcados como "external"#

Containers criados diretamente via CLI (docker run ou scripts externos) não possuem os metadados de controle de recursos do Portainer. O painel os classifica como "External". Se a interface estiver com filtros de usuário não administrativos ativos, esses containers podem ficar ocultos.

D. Módulos de segurança do kernel (AppArmor / SELinux)#

Políticas de segurança ativas no host podem bloquear o acesso ao socket montado dentro do container do Portainer, gerando negações silenciosas no kernel.

4. Diagnóstico prático passo a passo#

Para encontrar o ponto exato da falha na comunicação:

Passo 1: Verificar quem consome o socket#

lsof /var/run/docker.sock

Confirma quais processos e PIDs estão ativos no socket do Docker.

Passo 2: Testar a Docker API de dentro do container do Portainer#

É possível fazer uma requisição direta contra o socket montado no próprio container do Portainer:

docker exec -it portainer curl --unix-socket /var/run/docker.sock http://localhost/containers/json

• Se retornar o JSON com o container my-web-app: O backend do Portainer está conectado ao Docker normalmente. O problema é apenas filtro de exibição ou cache na interface do navegador.
• Se retornar erro de permissão ou conexão: O volume -v /var/run/docker.sock:... ou permissões do grupo estão barrando o acesso.

Passo 3: Inspecionar os logs do Portainer#

docker logs --tail 100 portainer

Permite identificar falhas de sincronização do ambiente local ou erros HTTP 403.

Passo 4: Checar bloqueios no kernel#

dmesg | grep -i deny

Identifica se o AppArmor ou SELinux rejeitou a abertura do descritor de arquivo.

5. Como oficializar o container como uma stack no Portainer#

Quando o container está rodando como External, você pode reiniciá-lo pela interface, mas não consegue editar variáveis de ambiente ou recriá-lo diretamente. A solução é convertê-lo em uma Stack (Docker Compose):

1. Inspecione os parâmetros atuais:

   docker inspect my-web-app

Anote as portas (8889:3000), variáveis e volumes.

1. Crie a Stack no Portainer:

Vá em Stacks > Add Stack e declare o arquivo Compose:

   version: '3.8'

   services:
     my-web-app:
       image: app-custom-image:latest
       container_name: my-web-app
       ports:
         - "8889:3000"
       restart: unless-stopped

1. Substituição controlada:

Pare e remova o container criado via CLI:

   docker stop my-web-app && docker rm my-web-app

Clique em Deploy the stack no Portainer. A partir desse momento, o serviço passa a ser gerenciado com ciclo de vida completo pela interface web.

Principais lições e takeaways#

1. Containers não precisam de importação manual: O Portainer reflete em tempo real o estado do dockerd consultando o socket Unix.
2. Se o container não aparece: Inspecione a montagem do volume /var/run/docker.sock e teste a conectividade com curl --unix-socket.
3. Containers de CLI viram "External": Para ter edição visual completa e redeploys declarativos, organize seus serviços utilizando Stacks.

Veja também

DevOps Desmistificando o coolify: arquitetura paas self-hosted, conflitos de reverse proxy e gestão de containers

DevOps A odisseia de rodar cPanel e systemd no Docker: de conflitos de Cgroups v1/v2 ao trap dos volumes persistentes

Linux Desmistificando o tmpfs: reduzir partições temporárias realmente libera RAM no Linux?

Este post está licenciado sob CC BY-NC.