Docker: Diagnóstico e Solução de Problemas Comuns em VPS

13 min 3 Docker Troubleshooting

Introdução: Mantenha seus Containers Docker Operacionais em um VPS

Manter aplicações em containers Docker rodando de forma estável em um servidor VPS é essencial para qualquer negócio que busca agilidade e eficiência. No entanto, é comum desenvolvedores e administradores de sistema se depararem com desafios como container docker reiniciando sozinho, o temido erro de docker sem espaço em disco, falhas ao tentar um erro no docker compose up, ou container não conecta na rede docker. Este guia completo, baseado na minha experiência de mais de 9 anos auxiliando clientes na Host You Secure, vai te equipar com as ferramentas e o conhecimento para diagnosticar e resolver esses problemas de forma eficaz, garantindo a alta disponibilidade das suas aplicações.

Veja a infraestrutura: VPS para Evolution API no Brasil para colocar este projeto no ar.

Para rodar suas aplicações Docker em produção com estabilidade, um VPS com no mínimo 4GB de RAM e 2 vCPUs é o ponto de partida recomendado, com o sistema operacional Ubuntu 22.04 LTS. Nossos clientes geralmente utilizam um plano como o VPS Brasil Básico para a maioria das stacks, como veremos adiante.

Diagnóstico de Containers Reiniciando Sozinhos

Por que meu container Docker está reiniciando inesperadamente? Containers reiniciando em loop são um dos problemas mais frustrantes e comuns, geralmente indicando que a aplicação dentro do container não está inicializando corretamente ou está falhando logo após iniciar. O sistema de gerenciamento do Docker, por padrão, tentará reiniciar o container para restaurar o serviço, o que pode mascarar a causa raiz se você não souber onde procurar.

Análise de Logs do Container

O primeiro passo para resolver um container que está reiniciando é sempre verificar os logs. Os logs contêm mensagens de erro e avisos que podem indicar o que está acontecendo dentro do container. Use o comando docker logs para isso:


docker logs --tail 100 --follow <nome_do_container_ou_id>

O parâmetro --tail 100 mostra as últimas 100 linhas e --follow mantém o fluxo de logs aberto, permitindo que você veja as mensagens em tempo real. Procure por mensagens de erro (geralmente em vermelho ou indicando 'ERROR', 'FATAL'), exceções ou segfaults. Em muitos casos, o problema pode ser uma variável de ambiente ausente, um arquivo de configuração incorreto, ou um erro no código da aplicação. Se você usa Docker Compose, pode usar docker compose logs -f <service_name> para o mesmo efeito.

Verificação da Saúde do Container

Além dos logs, verifique o status do container. O comando docker ps -a mostrará todos os containers, incluindo os que foram encerrados. Preste atenção na coluna 'STATUS' e 'RESTARTS'. Um container com muitos restarts e um status como 'Exited (1) X seconds ago' é um forte indício de falha na inicialização.


docker ps -a

Se o container está saindo rapidamente, você pode tentar executar o comando de inicialização manualmente para ver a saída. Por exemplo, se o Dockerfile usa CMD ["python", "app.py"], tente:


docker run --rm -it <nome_da_imagem> bash
# Dentro do container, execute o comando manualmente
python app.py

Isso permite um debug interativo, mostrando exatamente o que falha. Para mais detalhes sobre como resolver containers em loop infinito, confira nosso artigo Debugando Docker: Resolva Containers em Loop Infinito.

Resolvendo Problemas de Espaço em Disco no Docker

Por que meu Docker está sem espaço em disco? A falta de espaço em disco é um problema comum em ambientes Docker, especialmente em VPS com armazenamento limitado. Isso pode levar a falhas na inicialização de containers, impossibilidade de baixar novas imagens e erros de build. As principais causas são imagens e volumes não utilizados, além de logs de container excessivamente grandes.

Limpeza de Imagens, Containers e Volumes

O Docker armazena muitas camadas de imagens, containers parados e volumes órfãos que podem consumir gigabytes de espaço. A melhor maneira de liberar espaço é usar o comando docker system prune:


docker system prune --all --volumes

Este comando removerá:

  • Todos os containers parados
  • Todas as redes não utilizadas
  • Todas as imagens penduradas (sem tag)
  • Todos os volumes não utilizados (se --volumes for especificado)
  • Todo o cache de build do Docker

É crucial entender que --volumes removerá volumes que não estão associados a nenhum container, o que pode incluir dados importantes se você não tiver certeza de que são órfãos. Sempre faça backup de dados importantes antes de executar comandos de limpeza agressivos. Na minha experiência, muitos clientes esquecem de limpar volumes de bancos de dados antigos que foram recriados, mas os volumes originais ainda persistem.

Monitoramento e Gerenciamento de Logs

Containers podem gerar uma quantidade enorme de logs, preenchendo rapidamente o disco. Para verificar o tamanho dos logs de um container específico:


docker inspect --format='{{.LogPath}}' <nome_do_container>
# Em seguida, verifique o tamanho do arquivo:
du -sh $(docker inspect --format='{{.LogPath}}' <nome_do_container>)

Para limitar o tamanho dos logs, você pode configurar opções de log no seu docker-compose.yml ou ao rodar um container:


services:
  meuapp:
    image: minha-imagem
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Esta configuração limita o log a 3 arquivos de 10MB cada, totalizando 30MB por container. É uma prática excelente para evitar o docker sem espaço em disco devido a logs descontrolados.

Solucionando Erros no Docker Compose Up

Meu docker compose up está falhando, o que devo fazer? O Docker Compose é uma ferramenta poderosa para gerenciar aplicações multi-container, mas erros durante o docker compose up podem ser desafiadores. Eles geralmente se dividem em problemas de sintaxe no arquivo docker-compose.yml, falhas na construção de imagens ou dependências não resolvidas.

Validação do Arquivo docker-compose.yml

Erros de sintaxe são muito comuns. Use um validador YAML ou o próprio comando docker compose config para verificar seu arquivo:


docker compose config

Este comando irá analisar seu arquivo docker-compose.yml e mostrará a configuração final, ou reportará erros de sintaxe detalhados. Se houver um problema de indentação ou um caractere inválido, ele será exibido aqui. Lembre-se, o Compose v2 usa docker compose (com espaço) em vez de docker-compose (com hífen), que está descontinuado. Certifique-se de que seu sistema tem o plugin correto instalado: sudo apt install docker-compose-plugin.

Problemas de Rede e Portas

Conflitos de porta e problemas de rede são causas frequentes de falha. Se um serviço tenta expor uma porta que já está em uso por outro processo no host, o container não iniciará. Verifique as portas em uso com sudo ss -tulpn e ajuste seu docker-compose.yml ou libere a porta. Além disso, certifique-se de que os serviços dentro do seu docker-compose.yml podem se comunicar. Por exemplo, um serviço de aplicação precisando se conectar a um banco de dados:


version: '3.8'
services:
  app:
    image: minha-aplicacao
    ports:
      - "80:8000"
    environment:
      DATABASE_URL: "postgresql://user:password@db:5432/mydatabase"
    depends_on:
      - db

  db:
    image: postgres:14
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Neste exemplo, a aplicação usa db como hostname para se conectar ao banco de dados, que é o nome do serviço no docker-compose.yml. A rede interna do Docker Compose gerencia essa resolução de nomes automaticamente. Erros aqui levam a mensagens como container não conecta na rede docker.

Resolução de Problemas de Rede do Docker

Meu container não consegue se conectar à internet ou a outros containers, o que fazer? Problemas de rede são complexos no Docker, envolvendo configurações de rede, firewalls do host e a rede interna do Docker. Entender como o Docker gerencia as redes é crucial.

Verificação da Rede Interna e Externa

Cada vez que você inicia um docker compose up, uma rede bridge padrão é criada para seus serviços (a menos que você especifique uma). Containers dentro da mesma rede podem se comunicar usando seus nomes de serviço. Para listar as redes Docker:


docker network ls
docker network inspect <nome_da_rede>

Se um container precisa acessar um serviço externo ou a internet, ele usa a rede bridge padrão do Docker que, por sua vez, usa o NAT (Network Address Translation) do host para se conectar ao mundo exterior. Certifique-se de que o DNS do seu VPS está configurado corretamente e que não há bloqueios de firewall (como UFW ou Iptables) impedindo o tráfego de saída do Docker.

Configuração do Firewall (UFW)

O firewall UFW (Uncomplicated Firewall) pode causar problemas de conectividade se não for configurado para permitir o tráfego Docker. Por padrão, o Docker manipula as regras de iptables diretamente, mas o UFW pode interferir. Uma solução é permitir a sub-rede Docker:


sudo ufw allow in on docker0
sudo ufw allow out on docker0
sudo ufw reload

Se você estiver expondo portas para o mundo exterior (por exemplo, a porta 80 para um servidor web), certifique-se de que elas também estão permitidas no UFW: sudo ufw allow 80/tcp. Para cenários mais avançados com proxy reverso como Nginx, você pode precisar de regras específicas. Para mais informações sobre como resolver erros em seu VPS, acesse nosso artigo sobre Docker Troubleshooting: Resolva Erros em Seu VPS.

Passo a Passo: Deploy de uma Aplicação com Docker Compose em VPS

Para ilustrar as práticas de troubleshooting, vamos demonstrar o deploy de uma aplicação web simples (Nginx com um HTML estático) usando Docker Compose em um VPS Ubuntu. Isso nos permite simular um ambiente de produção e entender como lidar com problemas.

1. Preparação do VPS

Comece com um VPS Ubuntu 22.04 LTS. Conecte-se via SSH e atualize o sistema:


sudo apt update && sudo apt upgrade -y

Instale o Docker e o Docker Compose (o plugin oficial, não o binário antigo):


sudo apt install docker.io docker-compose-plugin -y
sudo usermod -aG docker $USER
newgrp docker

Isso permite que seu usuário execute comandos Docker sem sudo. Reinicie o terminal ou faça logoff/login para que as mudanças tenham efeito.

2. Criação do Arquivo docker-compose.yml

Crie uma pasta para sua aplicação e dentro dela, o arquivo docker-compose.yml. Vamos usar um exemplo simples com Nginx:


version: '3.8'
services:
  web:
    image: nginx:latest
    container_name: meu-nginx-web
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    restart: always
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "2"

Crie também um arquivo index.html dentro da pasta html:


<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Host You Secure - Docker Rodando!</title>
</head>
<body>
    <h1>Parabéns! Seu Nginx com Docker está funcionando na Host You Secure!</h1>
    <p>Este é um exemplo de aplicação simples rodando em Docker.</p>
</body>
</html>

3. Subindo a Aplicação

Na mesma pasta onde está o docker-compose.yml, execute o comando para subir a aplicação:


docker compose up -d

O -d significa 'detached mode', para rodar em segundo plano. Verifique o status:


docker ps

Agora, acesse o IP do seu VPS no navegador. Você deverá ver a página 'Parabéns! Seu Nginx com Docker está funcionando na Host You Secure!'. Se não funcionar, volte aos passos de diagnóstico de rede e logs.

Erros Comuns e Como Evitá-los

A experiência mostra que a maioria dos problemas com Docker pode ser evitada com boas práticas. Aqui estão alguns erros comuns:

Subdimensionamento de Recursos

Um erro frequente é tentar rodar aplicações Docker complexas em um VPS com pouca RAM ou CPU. Um container Nginx básico pode usar menos de 50MB de RAM, mas um banco de dados PostgreSQL pode facilmente consumir 500MB a 1GB, e uma aplicação Node.js ou Python pode precisar de mais 500MB a 1GB cada. Para um ambiente de produção com uma stack de aplicação, banco de dados e proxy reverso, 4GB de RAM e 2 vCPUs são o mínimo que eu recomendo para ter alguma folga e evitar problemas de memória (OOM Killer) ou performance. A aplicação em si pode consumir pouco, mas o ambiente Docker e o sistema operacional também demandam recursos.

Ignorar as Mensagens de Log

Muitos usuários ignoram os logs ou não sabem como interpretá-los. Eles são a sua principal fonte de verdade sobre o que está acontecendo dentro dos containers. Acostume-se a usar docker logs -f para monitorar e docker inspect para detalhes de configuração.

Não Gerenciar Volumes e Imagens

Deixar volumes órfãos e imagens antigas acumularem é a receita para o docker sem espaço em disco. Crie o hábito de executar docker system prune regularmente (sem --volumes se você não tiver certeza sobre a segurança dos dados) e sempre configure limites de log para seus containers em produção.

Ferramentas de Diagnóstico Docker

Ferramenta Propósito Principal Exemplo de Uso
docker logs Visualizar a saída e erros de um container `docker logs -f <nome_container>`
docker ps -a Listar containers (ativos e parados) e seus status/restarts `docker ps -a`
docker system prune Liberar espaço em disco removendo recursos não utilizados `docker system prune --all --volumes`
docker compose config Validar sintaxe do arquivo docker-compose.yml `docker compose config`
docker network inspect Detalhes sobre a configuração de uma rede Docker `docker network inspect bridge`

Perguntas Relacionadas

Como faço para parar todos os containers Docker de uma vez?

Para parar todos os containers em execução, você pode usar o comando docker stop $(docker ps -aq). O docker ps -aq lista os IDs de todos os containers, ativos ou inativos, que são então passados para o comando docker stop, encerrando-os de forma controlada.

Qual a diferença entre docker stop e docker kill?

docker stop envia um sinal SIGTERM ao container, dando à aplicação um tempo para encerrar gracefully (por padrão, 10 segundos). docker kill envia um sinal SIGKILL, que encerra o processo imediatamente e sem aviso, podendo levar à perda de dados não salvos. Use stop para desligamentos normais e kill apenas em emergências.

Como posso acessar arquivos dentro de um container Docker?

Você pode usar docker cp <nome_do_container>:/caminho/no/container /caminho/no/host para copiar arquivos de ou para um container. Alternativamente, para explorar interativamente, use docker exec -it <nome_do_container> bash (ou sh se bash não estiver disponível) para abrir um shell dentro do container.

É seguro rodar Docker em um VPS com 1GB de RAM?

Rodar Docker em um VPS com apenas 1GB de RAM é extremamente limitado e não recomendado para produção, exceto para containers muito pequenos e isolados. O próprio daemon do Docker e o sistema operacional já consomem uma parte significativa da memória. Para qualquer aplicação minimamente complexa, você enfrentará constantes problemas de Out Of Memory (OOM) e performance. Para produção, 4GB de RAM é o mínimo recomendado.

Conclusão: Estabilidade Docker com a Host You Secure

Dominar o diagnóstico e a solução de problemas do Docker é uma habilidade indispensável para quem gerencia aplicações em VPS. Ao seguir as práticas recomendadas de monitoramento de logs, gerenciamento de recursos e limpeza, você pode minimizar o tempo de inatividade e garantir que suas aplicações permaneçam robustas e responsivas. Problemas como container docker reiniciando sozinho, docker sem espaço em disco e erro no docker compose up são desafios superáveis com as ferramentas e o conhecimento certos.

Para garantir que suas aplicações Docker tenham o ambiente ideal para rodar, com recursos dedicados e performance, um VPS de qualidade é fundamental. Nossos clientes rodam essa mesma stack em uma VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs por apenas R$ 99/mês, perfeito para hospedar suas soluções Docker de forma eficiente e segura.

Perguntas Frequentes

Para verificar o status do daemon Docker, você pode usar o comando `sudo systemctl status docker`. Ele mostrará se o serviço está ativo (running), inativo ou se houve algum erro. Se não estiver rodando, use `sudo systemctl start docker` para iniciá-lo e `sudo systemctl enable docker` para garantir que ele inicie automaticamente com o sistema.

Um container 'Exited' indica que ele parou de rodar. Primeiro, verifique os logs com `docker logs <nome_do_container>` para identificar a causa do encerramento (erros na aplicação, configuração incorreta, etc.). Após corrigir o problema, tente iniciá-lo novamente com `docker start <nome_do_container>` ou recriá-lo se as mudanças exigirem uma nova imagem.

O comando `docker image prune -a` removerá todas as imagens Docker que não estão associadas a nenhum container existente. Isso inclui imagens 'dangling' (sem tag) e imagens que são base para containers parados. É uma ótima maneira de recuperar espaço em disco sem afetar containers em execução.

Para atualizar o Docker, siga as instruções oficiais de instalação para o seu sistema operacional, geralmente usando o gerenciador de pacotes (ex: `sudo apt update && sudo apt upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin`). Certifique-se de que não há containers críticos rodando ou que você tem um plano de backup antes de atualizar.

Comece verificando se as portas estão expostas corretamente no `docker-compose.yml` e se não há conflitos. Use `docker exec -it <container_name> ping <outro_container_ou_ip>` para testar a conectividade interna. No host, verifique o firewall (UFW/iptables) e as rotas de rede para garantir que o tráfego está sendo permitido de e para as interfaces Docker.

A lentidão pode vir de subdimensionamento de recursos (CPU/RAM), volumes com baixa performance (especialmente em HDD, prefira SSD), ou aplicações mal otimizadas. Monitore o uso de recursos do seu VPS e dos containers (`docker stats`). Otimize as imagens Docker para serem menores e use volumes nomeados para melhorar o I/O do disco.

Sim, é a forma recomendada de persistir dados de bancos de dados ou qualquer dado que precisa sobreviver à recriação de um container. Ao usar volumes, os dados são armazenados no sistema de arquivos do host, fora do container, garantindo que não sejam perdidos se o container for removido ou atualizado.

A opção `restart: always` faz com que o container tente reiniciar automaticamente sempre que parar, seja por um erro, desligamento do sistema ou reinicialização manual. É útil para garantir a alta disponibilidade da aplicação, mas pode mascarar problemas se o container estiver falhando repetidamente. É crucial monitorar os logs para entender a causa das paradas.

Comentários (0)

Ainda não há comentários. Seja o primeiro!