Guia prático de redes Docker

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.

1. O mapa mental das redes Docker (o que realmente existe)

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.

2. Conceito-chave: DNS interno do Docker

Este é o ponto mais ignorado, e o que mais causa problemas.

Dentro de uma rede Docker:

• Você não usa localhost para falar com outro contêiner.
• Você usa o nome do serviço (ou nome do contêiner).

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.

3. Portas: interna x externa (a confusão clássica)

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".

4. Criando redes do jeito certo

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.

5. Compose: onde tudo fica mais limpo

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:

• Organização
• Reprodutibilidade
• Zero dor com comandos longos
6. Comunicação: quem enxerga quem?

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


7. Banco de dados e "localhost": por que sempre falha

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.

8. Debug rápido (checklist)

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>


9. Boas práticas arquiteturais

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.

10. Mentalidade correta para redes Docker

Ao desenhar um ambiente, pergunte:

• 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?

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!