Índice do artigo
Docker Troubleshooting: O Que Fazer Quando Tudo Dá Errado no Seu VPS
Ao rodar aplicações em containers Docker no seu VPS, é comum encontrar desafios. Este guia prático se propõe a resolver os problemas mais frequentes que surgem, desde containers reiniciando sozinhos até a frustrante mensagem de erro no docker compose up. Nossa experiência na Host You Secure nos ensina que a chave para o sucesso com Docker em produção é ter um plano B e saber como diagnosticar problemas rapidamente. Se você está enfrentando dificuldades com seus containers Docker em um ambiente Linux, como Ubuntu, este artigo é o seu ponto de partida para estabilizar suas aplicações.
Veja a infraestrutura: VPS para Docker, Portainer e Coolify para colocar este projeto no ar.
Diagnóstico Inicial: Logs e Status dos Containers
O primeiro passo em qualquer cenário de troubleshooting é investigar os logs. O comando docker logs é seu melhor amigo. Ele exibe a saída padrão e de erro do container, fornecendo pistas valiosas sobre o que causou o problema. Se um container está reiniciando sozinho, os logs podem indicar uma falha na aplicação, um erro de configuração ou até mesmo um problema de recursos no host.
Verificando a Saúde do Host: Recursos do Servidor
Muitos problemas com Docker em um VPS estão diretamente ligados à falta de recursos do servidor. Um dos culpados mais comuns é o docker sem espaço em disco. O Docker pode consumir bastante espaço com imagens, contêineres parados, volumes e logs. Para verificar o uso de disco, utilize os comandos df -h para o sistema de arquivos e docker system df para ter uma visão específica do uso pelo Docker.
Se o problema for falta de espaço, você pode precisar limpar artefatos do Docker com docker system prune -a (use com cautela, pois remove tudo que não está em uso) ou aumentar o espaço de armazenamento do seu VPS. Outro recurso crítico é a memória RAM. Containers que consomem muita memória podem ser encerrados pelo sistema operacional (OOM Killer) se o host não tiver RAM suficiente. Verifique o uso de memória com free -m.
Resolução de Problemas Comuns de Rede
Um problema recorrente é o container não conecta na rede docker. Isso pode ocorrer por diversas razões, desde configurações incorretas do Docker Compose até conflitos de rede ou firewalls bloqueando portas. Ao usar docker compose up, verifique se as portas definidas no seu docker-compose.yml estão corretamente mapeadas e se não há outros serviços no host utilizando as mesmas portas.
Para solucionar problemas de rede, certifique-se de que os containers estejam na mesma rede, se precisarem se comunicar. Utilize o comando docker network ls para listar as redes e docker network inspect para ver os detalhes. Em ambientes de produção, é crucial configurar corretamente o proxy reverso (como Nginx ou Traefik) para expor os serviços externamente de forma segura.
Passo a Passo: Implantando uma Aplicação Docker em um VPS (Exemplo Prático)
Vamos demonstrar como implantar uma aplicação simples usando Docker e Docker Compose em um VPS com Ubuntu. Este exemplo servirá como base para entender a estrutura de arquivos e comandos necessários.
Pré-requisitos: Instalação do Docker e Docker Compose
Primeiro, certifique-se de que o Docker e o Docker Compose estejam instalados em seu VPS. Se você ainda não os instalou, pode seguir este guia prático para instalar e configurar o Docker em seu VPS.
# Atualizar lista de pacotes
sudo apt update
# Instalar Docker CE
sudo apt install docker.io
# Instalar Docker Compose Plugin (sintaxe v2)
sudo apt install docker-compose-plugin
# Adicionar seu usuário ao grupo docker para evitar usar sudo
sudo usermod -aG docker $USER
newgrp docker
# Verificar instalações
docker --version
docker compose version
Configurando o Arquivo Docker Compose
Crie um diretório para sua aplicação e, dentro dele, um arquivo chamado docker-compose.yml. Vamos usar um exemplo simples de um servidor web Nginx servindo uma página estática.
version: '3.8'
services:
web:
image: nginx:alpine
container_name: meu_servidor_web
ports:
- "8080:80"
volumes:
- ./html:/usr/share/nginx/html
restart: unless-stopped
networks:
default:
driver: bridge
Criando o Conteúdo da Aplicação
Crie um subdiretório chamado html e dentro dele um arquivo index.html:
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Teste Docker VPS</title>
</head>
<body>
<h1>Olá do meu VPS com Docker!</h1>
<p>Esta página está sendo servida por um container Nginx.</p>
</body>
</html>
Iniciando os Containers
Agora, use o Docker Compose para iniciar os serviços. Para um ambiente de produção, o VPS Brasil Básico (R$ 99/mês, 4GB RAM, 4 vCPUs) é uma excelente opção para rodar stacks como esta, garantindo performance e estabilidade. Temos esse mesmo stack em produção em uma VPS Brasil Básico.
docker compose up -d
O comando -d inicia os containers em modo detached (em segundo plano). Você pode verificar se os containers estão rodando com docker ps.
Verificando o Acesso
Acesse seu VPS através do navegador usando o IP do seu servidor na porta 8080 (ou a porta que você definiu em ports). Por exemplo: http://seu_ip_do_vps:8080.
Erros Comuns e Soluções Rápidas
Container Reinicia Sozinho (Loop Infinito)
Se um container está em um loop de reinício, a causa mais provável é um erro na aplicação que o container executa, ou uma falha na configuração que impede o serviço de iniciar corretamente. O primeiro passo é sempre docker logs . Se os logs não forem claros, verifique se a imagem Docker está correta, se os volumes estão montados adequadamente e se as variáveis de ambiente estão definidas.
Docker Sem Espaço em Disco
Como mencionado, o acúmulo de imagens não utilizadas, contêineres parados e logs pode esgotar o espaço em disco. Use docker system prune -a --volumes (com muito cuidado!) para limpar tudo que não está sendo usado ativamente. Em muitos casos, um reinício do Docker daemon ou do servidor pode liberar espaço temporariamente, mas a limpeza regular é essencial.
Erro no Docker Compose Up
Mensagens de erro durante docker compose up geralmente indicam problemas de sintaxe no arquivo docker-compose.yml, conflitos de portas, dependências não atendidas entre serviços, ou falhas ao baixar imagens. Sempre verifique a sintaxe do YAML, certifique-se de que as portas não estão em uso por outros processos no host e que todas as imagens especificadas existem e estão acessíveis.
Container Não Conecta na Rede Docker
Este erro pode ser complexo. Se os containers estão em redes diferentes e precisam se comunicar, você precisará conectá-los explicitamente ou colocá-los na mesma rede customizada. Verifique também as configurações de firewall do seu VPS. O Docker cria suas próprias redes, e às vezes regras de firewall podem interferir na comunicação entre containers ou entre o host e os containers.
Perguntas Relacionadas
Por que meu container Docker fica reiniciando?
Um container que reinicia sozinho geralmente indica que o processo principal dentro dele falhou. Isso pode ser causado por um erro de código na aplicação, um arquivo de configuração corrompido, dependências ausentes ou falta de recursos no servidor host (como memória RAM). Analisar os logs do container com docker logs é o primeiro passo para identificar a causa específica.
Como liberar espaço em disco do Docker?
O Docker acumula imagens, contêineres parados, volumes e cache de build. Use docker system prune para remover contêineres parados, redes não usadas e imagens sem tag. Para remover volumes órfãos, use docker volume prune. O comando docker system prune -a --volumes é mais agressivo e remove tudo que não está ativamente em uso, incluindo volumes. Use com cautela e certifique-se de não apagar dados importantes.
O que fazer quando `docker compose up` falha?
Falhas no docker compose up podem ser devido a erros de sintaxe no arquivo docker-compose.yml, portas já em uso no host, problemas de permissão, ou falhas ao baixar as imagens Docker necessárias. Verifique os logs de erro do Compose, confirme se as portas estão livres com sudo ss -tulnp | grep , e garanta que as imagens estejam acessíveis.
Como diagnosticar problemas de rede entre containers Docker?
Problemas de rede em Docker podem ser diagnosticados verificando as redes às quais os containers pertencem com docker network ls e docker network inspect. Certifique-se de que os containers que precisam se comunicar estejam na mesma rede. Use ferramentas como ping ou curl dentro de um container para testar a conectividade com outro container ou serviço externo.
Comparativo: Requisitos de Servidor para Docker em Produção
| Critério | Ambiente de Teste/Desenvolvimento | Produção Leve | Produção Robusta |
|---|---|---|---|
| RAM | 2 GB | 4 GB | 8 GB+ |
| vCPUs | 1-2 | 2-4 | 4+ |
| Espaço em Disco | 20 GB | 50 GB+ | 100 GB+ (dependendo dos dados/logs) |
| Logs | Gerenciamento básico | Configuração de rotação/retirada | Sistema de log centralizado, rotação agressiva |
| Backup | Manual ocasional | Automatizado diário (volumes/dados) | Automatizado frequente, testes de restauração |
O que devo considerar ao escolher um VPS para Docker?
Ao escolher um VPS para rodar Docker, priorize recursos de RAM e CPU adequados para suas aplicações. Para aplicações self-hosted que dependem de Docker, como muitas ferramentas de automação e back-end, um VPS com no mínimo 4GB de RAM e 2 vCPUs é recomendado para um ambiente de produção estável. O espaço em disco deve ser suficiente para as imagens, contêineres em execução, volumes de dados e logs. Considere também a localização do servidor para latência e a qualidade do suporte técnico.
Conclusão e Próximos Passos
Dominar o troubleshooting de Docker em um VPS é essencial para manter suas aplicações funcionando sem interrupções. Desde a verificação de recursos do servidor até a depuração de redes e logs, cada passo é crucial. Lembre-se de que a prevenção é o melhor remédio: mantenha seus sistemas atualizados, monitore o uso de recursos e tenha backups regulares. Se você está pronto para implantar suas aplicações Docker com confiança e performance, a Host You Secure oferece a infraestrutura ideal.
Para uma solução robusta e otimizada para rodar suas aplicações Docker, recomendamos o plano VPS Brasil Básico. Ele oferece 4GB de RAM e 4 vCPUs, sendo ideal para hospedar stacks complexos de forma confiável. Temos esse mesmo stack em produção em uma VPS Brasil Básico.
Adquira seu VPS Brasil Básico agora e garanta a estabilidade das suas aplicações Docker!
FAQ: perguntas frequentes
O que causa um container Docker a reiniciar sozinho?
Um container reiniciando sozinho geralmente indica uma falha interna. Isso pode ser devido a um erro no código da aplicação rodando dentro do container, um problema de configuração, dependências ausentes ou a falta de recursos do servidor host, como memória RAM insuficiente, que leva o sistema a encerrar o container (OOM Killer).
Como posso liberar espaço em disco ocupado pelo Docker?
Para liberar espaço, você pode usar comandos como <code>docker system prune</code> para remover contêineres parados, redes não utilizadas e imagens sem tag. <code>docker volume prune</code> remove volumes não utilizados. O comando <code>docker system prune -a --volumes</code> é mais agressivo e remove tudo que não está ativamente em uso. É crucial ter cuidado para não apagar dados importantes.
Quais são os erros mais comuns ao usar 'docker compose up'?
Os erros comuns incluem sintaxe incorreta no arquivo <code>docker-compose.yml</code>, portas já em uso no host que impedem o mapeamento, problemas de permissão de arquivos ou diretórios, falhas ao baixar imagens Docker necessárias ou conflitos de rede. Verifique sempre os logs de erro fornecidos pelo Docker Compose.
Como resolver problemas de conectividade de rede entre containers Docker?
Verifique se os containers estão na mesma rede Docker ou se as redes foram configuradas corretamente para permitir a comunicação. Use <code>docker network inspect</code> para entender a topologia da rede. Certifique-se de que firewalls no host não estejam bloqueando as portas necessárias para a comunicação entre os serviços.
Qual a quantidade mínima de RAM recomendada para rodar Docker em produção?
Para um ambiente de produção estável, especialmente com múltiplas aplicações ou serviços rodando em containers, recomendamos no mínimo 4GB de RAM. Para cargas de trabalho mais pesadas ou um número maior de containers, 8GB ou mais é mais adequado para garantir performance e evitar o OOM Killer.
Como monitorar o uso de recursos do Docker em um VPS?
Você pode usar comandos do sistema como <code>top</code>, <code>htop</code> e <code>free -m</code> para monitorar o uso geral de CPU e memória do host. Para o Docker especificamente, <code>docker stats</code> fornece uma visão em tempo real do consumo de CPU, memória, rede e I/O de cada container em execução, o que é essencial para identificar gargalos.
O que é o OOM Killer e como ele afeta meus containers Docker?
O OOM Killer (Out-Of-Memory Killer) é um processo do kernel Linux que encerra processos para liberar memória quando o sistema está sob pressão de memória. Se seus containers consomem mais RAM do que o disponível no VPS, o OOM Killer pode encerrá-los abruptamente, fazendo com que reiniciem ou falhem. Monitorar o uso de RAM e definir limites de memória para os containers pode ajudar a mitigar isso.
Como garantir que meus containers Docker sejam reiniciados automaticamente após uma falha ou reinicialização do servidor?
No seu arquivo <code>docker-compose.yml</code>, você pode definir a política de reinicialização para cada serviço. Use `restart: unless-stopped` para que o container reinicie automaticamente caso falhe ou após uma reinicialização do Docker daemon ou do servidor, mas não reinicie se você explicitamente o parar. `restart: always` tentará reiniciar sempre, mesmo se você o parar manualmente, o que pode ser indesejado.