Entenda o essencial e pare de sofrer
Por que redes Docker importam?
Contêineres são processos isolados. Para que conversem entre si e com o mundo externo, precisam de rede.
Quando você ignora esse ponto, surgem sintomas típicos:
- "O container sobe, mas o app não conecta ao banco."
- "Funciona no meu computador, mas não no servidor."
- "Consigo acessar localhost, mas o container não."
Quase sempre, a raiz do problema é como a rede foi criada ou usada.
- O mapa mental das redes Docker (o que realmente existe)
- Conceito-chave: DNS interno do Docker
- Você não usa localhost para falar com outro contêiner.
- Você usa o nome do serviço (ou nome do contêiner).
- Portas: interna x externa (a confusão clássica)
- Criando redes do jeito certo
- Compose: onde tudo fica mais limpo
- Organização
- Reprodutibilidade
- Zero dor com comandos longos
- Comunicação: quem enxerga quem?
- Banco de dados e "localhost": por que sempre falha
- Debug rápido (checklist)
- Boas práticas arquiteturais
- Mentalidade correta para redes Docker
- Quem precisa falar com quem?
- Essa comunicação é interna ou externa?
- Existe risco se alguém fora enxergar este serviço?
- Preciso compartilhar a rede com outros projetos?
Quando você instala Docker, ele cria automaticamente três redes:
| Rede | Descrição | Quando usar | Observações importantes |
|---|---|---|---|
| bridge | Rede padrão criada pelo Docker para comunicação entre contêineres no mesmo host. | Desenvolvimento local e aplicações simples com múltiplos contêineres. | Possui DNS interno; contêineres se comunicam pelo nome. É a base da maioria dos projetos com Docker Compose. |
| host | Remove o isolamento de rede; o contêiner utiliza diretamente a rede do host. | Casos específicos de performance ou necessidade de acesso direto à rede do host. | Elimina o mapeamento de portas. Reduz isolamento e aumenta riscos se usado sem critério. |
| none | Contêiner sem qualquer interface de rede configurada. | Jobs isolados, processamento offline ou tarefas batch. | Não permite comunicação externa ou interna. Uso pouco comum em aplicações web. |
Na maioria dos projetos, você vai trabalhar quase sempre com "bridge", normalmente criada com docker network create.
Este é o ponto mais ignorado, e o que mais causa problemas.
Dentro de uma rede Docker:
Exemplo no docker-compose.yml:
services:
api:
image: minhaapi
depends_on:
- db
db:
image: postgres:16
A aplicação "api" deve conectar no banco usando:
DB_HOST=db
e não:
DB_HOST=localhost
Regra mental simples: no Docker, serviços conversam pelo nome.
Quando você publica uma porta, faz um mapeamento:
-p 8080:8080
Leia assim:
porta_do_host : porta_do_container
-O contêiner continua ouvindo dentro dele (porta interna).
-O host expõe a porta para fora.
Se você esquecer o -p, o serviço funciona entre containers, mas não de fora para dentro, e parece "quebrado".
Crie explicitamente uma rede para seu projeto:
docker network create minha-rede
Quando subir containers:
docker run -d --name api --network minha-rede minhaapi docker run -d --name db --network minha-rede postgres:16
Agora ambos:
Estão isolados de outros projetos.
Podem se resolver por nome.
Não "vazam" comunicação desnecessária.
No docker-compose.yml, usar rede é natural:
services:
api:
image: minhaapi
ports:
- "8080:8080"
depends_on:
- db
networks:
- appnet
db:
image: postgres:16
networks:
- appnet
networks:
appnet:
driver: bridge
Você ganha:
Contêineres na mesma rede -> conversam entre si.
Contêineres em redes diferentes -> não conversam (a menos que você conecte).
Host acessa container exposto via localhost:porta_publicada.
Quer conectar um container a outra rede?
docker network connect outra-rede api Cenário comum:
App Java no container
Banco PostgreSQL no container
Conexão configurada para localhost
Resultado: erro.
Explicação curta: "localhost" dentro do container aponta para ele mesmo, não para outro container.
Use:
jdbc:postgresql://db:5432/meubanco
Simples assim.
Quando algo "não comunica", verifique:
O container está na mesma rede?
Estou usando nome do serviço, não localhost?
A porta está publicada (-p) quando preciso acessar do host?
O container de destino realmente está ouvindo na porta esperada?
Compose não está criando uma rede automática diferente?
Ferramentas úteis:
docker network ls docker network inspect <nome> docker container inspect <nome> Uma rede por sistema (ou domínio lógico).
Não expose banco de dados para fora sem necessidade.
Use nomes estáveis de serviços.
Documente portas e dependências.
Prefira docker compose ao invés de comandos manuais.
Ao desenhar um ambiente, pergunte:
Responder isso antes evita retrabalho depois.
Considerações finais
Docker Networks não são complicadas, apenas exigem um modelo mental correto:
- containers conversam por nomes
- redes definem fronteiras
- portas definem exposição
- compose organiza tudo
Dominar estes fundamentos elimina a maior parte dos problemas de conectividade e devolve tempo para o que realmente importa: entregar software.
Feito!
