Proxy Docker: O guia completo para fazer os contêineres funcionarem atrás dos firewalls corporativos

A maioria das redes corporativas usa servidores proxy pra monitorar e filtrar o tráfego da internet. Isso cria obstáculos quando o Docker tenta puxar imagens dos registros. Você vai ter problemas com tempo limite de conexão, erros de autenticação e compilações que não funcionam na sua rede doméstica. Esses problemas com proxy podem atrapalhar as equipes de desenvolvimento que não conseguem acessar as imagens básicas de que precisam.

A configuração do proxy do Docker resolve esses problemas de conectividade, melhorando o desempenho com cache e atendendo aos requisitos de segurança da empresa. Depois de configurados, seus contêineres vão puxar imagens independentemente das restrições de rede.

Neste tutorial, vou te mostrar como configurar as definições do proxy do daemon do Docker, as variáveis de ambiente do contêiner e como lidar com a configuração do proxy no Docker Compose.

Você é novo no Docker e tá se sentindo meio perdido com todos esses conceitos de rede? Comece com o básico do Docker e ganhe confiança passo a passo.

Entendendo a arquitetura do proxy do Docker

Diferentes partes do ecossistema Docker precisam de configuração de proxy em diferentes camadas.

Os proxies são tipo intermediários entre os seus componentes Docker e as redes externas. Quando o Docker precisa puxar imagens, os contêineres precisam de acesso à Internet ou as compilações exigem recursos externos, os servidores proxy controlam e monitoram essas conexões. Eles ficam entre suas aplicações em contêineres e o mundo exterior, filtrando solicitações e respostas.

As empresas usam proxies com o Docker pra melhorar o desempenho, a segurança e a conformidade.

O desempenho vem do armazenamento em cache de recursos acessados com frequência, como imagens básicas, reduzindo o tempo de download para toda a equipe. Os benefícios de segurança incluem filtragem de tráfego, verificação de malware e bloqueio de acesso a sites não autorizados. Os requisitos de conformidade exigem que todo o tráfego de rede passe por canais monitorados com controles de acesso adequados e registros de auditoria.

A configuração do proxy do Docker rola em quatro camadas:

• Proxy do cliente: afeta comandos da CLI do Docker, como docker pull e docker push

• Proxy do daemon: controla como o daemon do Docker acessa registros externos

• Proxy de tempo de execução do contêiner: define variáveis proxy para aplicativos dentro de contêineres

• Proxy de tempo de compilação: cuida das configurações de proxy durante as operações de “ docker build ” quando os Dockerfiles precisam de acesso à Internet.

Cada camada tem uma função e precisa de uma configuração diferente.

Pra entender como funciona a rede do Docker, primeiro é preciso saber como os contêineres se comunicam. 

Configurando o Docker para usar um proxy

Pra fazer o Docker funcionar com o proxy da sua empresa, você precisa configurar tanto o daemon quanto o cliente do Docker.

Por quê? Porque eles lidam com diferentes tipos de solicitações de rede. 

O daemon cuida de puxar e enviar imagens e autenticar o registro, enquanto o cliente dá conta das operações da CLI e das chamadas da API. Se alguma dessas configurações estiver faltando, vai ter lacunas que podem fazer com que as operações do Docker falhem com erros de conexão.

Como configurar o daemon do Docker

O daemon do Docker lê as configurações de proxy em /etc/docker/daemon.json. Crie esse arquivo se ele não existir:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

O campo “ noProxy ” tem os endereços que não precisam passar pelo proxy. Inclua aqui os domínios do seu registro interno e os endereços localhost.

Configurando substituições do serviço systemd

Em sistemas Linux baseados em systemd, você também precisa configurar o próprio serviço Docker para usar o proxy. Crie o diretório de substituição e o arquivo de configuração:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Depois, coloca essas variáveis de ambiente no arquivo http-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.company.com"

Isso garante que o próprio processo do daemon do Docker consiga acessar serviços externos através do seu proxy.

O Docker não vai pegar as mudanças no proxy até você reiniciar o daemon. Execute esses comandos para recarregar o systemd e reiniciar o Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

O comando “daemon reload” diz ao systemd para ler a nova configuração do serviço, enquanto o comando “docker restart” aplica as alterações no arquivo “ daemon.json ”.

Coisas específicas da plataforma

O Docker Desktop lida com a configuração de proxy de maneira diferente das instalações em servidor. No Windows e no macOS, use a interface gráfica do Docker Desktop para definir as configurações de proxy na seção Recursos - Proxies. Essas configurações ajustam automaticamente tanto o daemon quanto o cliente.

Os hosts Linux que usam o Docker Engine precisam da configuração manual descrita acima. Algumas distribuições empacotam o Docker de forma diferente, então dá uma olhada se o seu sistema usa o dockerd direto ou através de um gerenciador de serviços diferente.

Verificando sua configuração

Teste se o Docker consegue acessar registros externos com um comando pull simples:

docker pull hello-world

Você também pode conferir a configuração do daemon:

docker system info | grep -i proxy

Isso mostra se o Docker detectou e aplicou suas configurações de proxy.

Se ainda assim não funcionar, dá uma olhada nos logs do seu servidor proxy pra confirmar se o Docker tá encaminhando as solicitações direitinho.

Problemas de rede te deixaram preso? Exponha as portas do Docker da maneira certa pra evitar problemas de conexão.

Configurando variáveis de ambiente proxy

Os comandos da CLI do Docker precisam de uma configuração de proxy separada das configurações do daemon. As variáveis de ambiente oferecem controle flexível sobre como os clientes Docker se conectam por meio de proxies corporativos.

Os proxies do cliente controlam as operações da CLI do Docker, como docker pull, docker push e docker login. Quando você executa esses comandos, o cliente Docker faz solicitações HTTP para registros e precisa saber qual servidor proxy usar. Sem as configurações de proxy do cliente, essas operações falham mesmo quando o daemon está configurado corretamente.

Método de configuração JSON

A maneira mais simples é usar o arquivo de configuração do Docker em ~/.docker/config.json:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

Esse método mantém as configurações de proxy dentro da configuração do Docker e não afeta outros aplicativos no seu sistema.

Alternativa à variável de ambiente

Você também pode definir variáveis de ambiente proxy padrão que o Docker vai detectar automaticamente usando esses comandos:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

Essas variáveis funcionam para qualquer aplicativo que respeite os padrões de proxy, não só o Docker.

Configuração global vs. por usuário

Para configurar em todo o sistema, adicione as variáveis de ambiente em /etc/environment ou crie um script em /etc/profile.d/:

# /etc/profile.d/proxy.sh
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

Para configurar por usuário, adicione-os ao seu perfil shell (~/.bashrc, ~/.zshrc) ou use o método de configuração JSON. As configurações por usuário dão aos desenvolvedores a flexibilidade de usar proxies diferentes ou ignorá-los completamente para testes.

Considerações de segurança

Nunca coloque nomes de usuário e senhas em arquivos de configuração ou variáveis de ambiente. 

As credenciais de proxy em texto simples podem ser um risco de segurança, principalmente em ambientes compartilhados ou sistemas de controle de versão.

Em vez disso, use estas abordagens:

• Configure seu servidor proxy para autenticação baseada em IP, se possível.
• Use ajudantes de credenciais ou sistemas de armazenamento seguro para autenticação.
• Configure contas de serviço com permissões mínimas para operações do Docker

Se você precisar incluir credenciais, use o formato http://username:password@proxy.company.com:8080, mas guarde-as em arquivos protegidos com permissões restritas.

Configuração do proxy na hora da compilação

As compilações do Docker precisam que as configurações de proxy sejam passadas explicitamente por meio de argumentos de compilação:

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t myapp .

Os argumentos de compilação viram variáveis de ambiente dentro do contexto de compilação.

Isso permite que as instruções “ RUN ” baixem pacotes e dependências através do seu proxy. Sem esses argumentos, as compilações falham quando os Dockerfiles tentam instalar software ou buscar recursos da Internet.

As configurações de proxy de tempo de compilação não ficam na imagem final, a menos que você as defina explicitamente com instruções ENV no seu Dockerfile.

As variáveis de ambiente oferecem flexibilidade para lidar com as configurações de proxy no nível certo para o seu fluxo de trabalho.

Você acha as discussões sobre compilação confusas? Domine os argumentos de compilação do Docker com exemplos reais que realmente funcionam.

Injeção de proxy em contêiner e em tempo de compilação

A configuração do cliente Docker só te leva até a metade do caminho — seus contêineres e compilações precisam de suas próprias configurações de proxy. Nesta seção, vou mostrar como injetar a configuração do proxy em tempo de execução e em tempo de compilação.

Variáveis de ambiente de tempo de execução

Os contêineres não pegam as configurações de proxy do seu host.

Você precisa passar variáveis proxy explicitamente ao iniciar contêineres. O Docker oferece várias maneiras de fazer isso, dependendo se você quer configurar todos os contêineres ou só alguns específicos.

A configuração JSON é a maneira mais simples de definir proxy de forma consistente, como falamos antes. Para recapitular, adicione isso ao seu arquivo ~/.docker/config.json:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

O Docker coloca essas variáveis automaticamente em todos os contêineres que você inicia. Não precisa de sinalização extra.

Os sinalizadores CLI te dão mais controle por contêiner:

docker run \
  --env HTTP_PROXY=http://proxy.company.com:8080 \
  --env HTTPS_PROXY=http://proxy.company.com:8080 \
  --env NO_PROXY=localhost,127.0.0.1 \
  nginx

Você também pode passar um arquivo de ambiente inteiro:

# proxy.env
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1

docker run --env-file proxy.env nginx

Os contêineres já existentes podem receber variáveis proxy depois de começarem a funcionar usando docker exec:

docker exec -e HTTP_PROXY=http://proxy.company.com:8080 container_name curl google.com

Essa abordagem funciona para comandos únicos, mas não continua depois que o contêiner é reiniciado.

Configuração do proxy na hora da compilação

A criação de imagens falha em ambientes proxy, a menos que você passe explicitamente as configurações de proxy.

Os argumentos de compilação são a maneira padrão de colocar variáveis proxy durante as compilações:

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  --tag myapp .

Seu Dockerfile precisa declarar esses argumentos para usá-los:

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Use proxy for package installation
RUN apt-get update && apt-get install -y curl

# Don't persist proxy in final image

As declarações do Dockerfile permitem definir valores padrão para o proxy:

ARG HTTP_PROXY=http://proxy.company.com:8080
ARG HTTPS_PROXY=http://proxy.company.com:8080

ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN pip install requests

A instrução ` ENV ` deixa as variáveis proxy disponíveis para todos os comandos ` RUN ` que vêm depois na sua compilação.

É bom saber que as limitações do BuildKit podem causar problemas de proxy com versões mais recentes do Docker. O BuildKit armazena contextos de compilação de forma agressiva, o que às vezes ignora alterações no proxy.

Você pode forçar o BuildKit a reconhecer atualizações de proxy:

DOCKER_BUILDKIT=1 docker build \
  --no-cache \
  --build-arg HTTP_PROXY=$HTTP_PROXY \
  --tag myapp .

Ou você pode desativar o BuildKit completamente para compilações sensíveis a proxy:

DOCKER_BUILDKIT=0 docker build --build-arg HTTP_PROXY=$HTTP_PROXY --tag myapp .

Quando se trata de compilações em várias etapas, é preciso ter uma configuração de proxy consistente em todas as etapas:

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Build stage
FROM python:3.13 AS builder
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

COPY requirements.txt .
RUN pip install -r requirements.txt

# Runtime stage
FROM python:3.13-slim AS runtime
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

COPY --from=builder /usr/local/lib/python*/site-packages /usr/local/lib/python*/site-packages
RUN apt-get update && apt-get install -y curl

# Clear proxy variables for final image
ENV HTTP_PROXY=
ENV HTTPS_PROXY=
ENV NO_PROXY=

Cada etapa pega os argumentos de compilação, mas não as variáveis de ambiente das etapas anteriores. Defina as variáveis proxy explicitamente em todas as etapas que precisarem delas.

Resumindo: configura uma vez, usa em todo o lado.

Tá confuso sobre ENTRYPOINT e CMD nos seus contêineres habilitados para proxy? Veja tudo detalhadamente com exemplos práticos.

Configurando gerenciadores de pacotes para usar um proxy em contêineres

As configurações de proxy do Docker não são automaticamente transferidas para os gerenciadores de pacotes dentro dos seus contêineres. Você precisa configurar cada gerenciador de pacotes separadamente para baixar pacotes através do proxy da sua empresa.

Gerenciadores de pacotes como apt-get, yum e apk fazem conexões HTTP diretas com repositórios de pacotes. Em redes com restrições, essas conexões não funcionam a menos que o gerenciador de pacotes saiba sobre o seu servidor proxy.

As variáveis de ambiente padrão não são suficientes. A maioria dos gerenciadores de pacotes tem seus próprios arquivos de configuração que substituem as configurações de proxy do sistema.

Ubuntu/Debian: configuração do apt-get

Crie um arquivo de configuração de proxy que o apt-get vai ler durante a instalação do pacote.

Adicione isso ao seu Dockerfile:

FROM python:3.13

# Configure apt proxy
RUN echo 'Acquire::http::Proxy "http://proxy.company.com:8080";' > /etc/apt/apt.conf.d/proxy.conf && \
    echo 'Acquire::https::Proxy "http://proxy.company.com:8080";' >> /etc/apt/apt.conf.d/proxy.conf

RUN apt-get update && apt-get install -y curl wget

O arquivo “ /etc/apt/apt.conf.d/proxy.conf ” diz ao “ apt-get ” para passar todos os downloads de pacotes pelo seu proxy. O arquivo continua lá mesmo depois de você usar o comando “ RUN ” na sua compilação.

Você também pode definir exclusões de proxy para repositórios internos:

RUN echo 'Acquire::http::Proxy::internal.company.com "DIRECT";' >> /etc/apt/apt.conf.d/proxy.conf

Alpine Linux: configuração do apk

O Alpine usa o gerenciador de pacotes apk, que lê as configurações de proxy em /etc/apk/repositories e nas variáveis de ambiente.

FROM python:3.13-alpine

# Configure apk proxy
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080

RUN apk add --no-cache curl wget

apk O Alpine respeita as variáveis de ambiente padrão do proxy HTTP, então você não precisa de arquivos de configuração separados. Mas você pode criar um pra ter mais controle:

RUN echo 'http_proxy=http://proxy.company.com:8080' > /etc/environment && \
    echo 'https_proxy=http://proxy.company.com:8080' >> /etc/environment

CentOS/RHEL: configuração do yum

Os sistemas CentOS e RHEL usam yum ou dnf, que leem as configurações de proxy em /etc/yum.conf.

FROM centos:8

# Configure yum proxy
RUN echo 'proxy=http://proxy.company.com:8080' >> /etc/yum.conf

RUN yum update -y && yum install -y curl wget

Para versões mais recentes do CentOS que usam o gerenciador de pacotes dnf, use o seguinte:

FROM centos:stream9

# Configure dnf proxy
RUN echo 'proxy=http://proxy.company.com:8080' >> /etc/dnf/dnf.conf

RUN dnf update -y && dnf install -y curl wget

Você também pode excluir domínios específicos do roteamento do proxy adicionando este comando:

RUN echo 'proxy_exclude=internal.company.com,localhost' >> /etc/yum.conf

Testando a funcionalidade do proxy

Primeiro, você precisa verificar se o seu gerenciador de pacotes consegue acessar os repositórios através do proxy.

Adicione comandos de teste ao seu Dockerfile:

FROM python:3.13

# Configure proxy
RUN echo 'Acquire::http::Proxy "http://proxy.company.com:8080";' > /etc/apt/apt.conf.d/proxy.conf

# Test package manager connectivity
RUN apt-get update && \
    apt-get install -y --dry-run curl && \
    echo "Package manager proxy test passed"

# Install actual packages
RUN apt-get install -y curl python3-pip

A bandeira ` --dry-run ` testa a resolução do pacote sem realmente instalar nada. Se der certo, a configuração do seu proxy tá funcionando.

Você também pode testar com saída detalhada para depurar problemas de conexão:

RUN apt-get -o Debug::Acquire::http=true update

Isso mostra exatamente quais URLs o apt-get tenta acessar e se as conexões proxy funcionam.

Para testes alpinos, use o seguinte:

RUN apk update --verbose && \
    apk add --simulate curl && \
    echo "Alpine proxy test passed"

Resumindo, configure cada gerenciador de pacotes individualmente e suas compilações funcionarão atrás de qualquer proxy.

Precisa limpar artefatos de compilação relacionados ao proxy? Os comandos prune do Docker vão liberar espaço e manter seu sistema limpo.

Implementações avançadas de proxy

Os proxies HTTP básicos são bons pra começar, mas os ambientes de produção precisam de mais controle sobre o acesso ao registro e o cache de imagens. Veja como configurar proxies de cache e espelhos de registro para melhorar o desempenho e a confiabilidade.

Registros de proxy de cache

Puxar as mesmas imagens base várias vezes desperdiça largura de banda e deixa as compilações mais lentas.

Os proxies de cache ficam entre seus clientes Docker e registros externos, como o Docker Hub. Eles guardam as imagens que você usa mais no seu computador, então, da próxima vez que você precisar delas, elas vão aparecer na sua rede interna, em vez de ter que pegar da internet.

A escolha mais popular para ambientes empresariais é o Harbor:

# docker-compose.yml for Harbor
version: '3.8'
services:
  harbor-core:
    image: goharbor/harbor-core:v2.8.0
    environment:
      - CORE_SECRET=your-secret-key
      - JOBSERVICE_SECRET=your-job-secret
    ports:
      - "80:8080"
    volumes:
      - ./harbor.yml:/etc/core/app.conf

Você pode configurar o Harbor como um cache proxy editando harbor.yml:

# harbor.yml
hostname: harbor.company.com
http:
  port: 80

database:
  password: harbor-db-password

data_volume: /data

proxy_cache:
  - endpoint: https://registry-1.docker.io
    username: your-dockerhub-username
    password: your-dockerhub-token

Se você precisa de uma alternativa mais simples para o cache básico, use o Docker Registry Proxy. Veja como:

docker run -d \
  --name registry-proxy \
  -p 5000:5000 \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -v registry-cache:/var/lib/registry \
  registry:2

Depois, aponte seus clientes Docker para o proxy de cache:

{
  "registry-mirrors": ["http://harbor.company.com"]
}

Aqui estão todos os benefícios que você ganha com proxies de cache:

• Imagens mais rápidas após o primeiro download
• Menos uso da banda larga da internet
• Melhorar a confiabilidade da compilação quando os registros externos apresentam problemas
• Controle de acesso centralizado e digitalização de imagens

Espelhos de registro e BuildKit

Os espelhos de registro permitem redirecionar as solicitações de imagens para registros internos ou geograficamente mais próximos.

A configuração de espelho único direciona todas as solicitações do Docker Hub por meio de um espelho:

{
  "registry-mirrors": ["https://mirror.company.com"],
  "insecure-registries": ["harbor.company.com:5000"]
}

Adicione isso a /etc/docker/daemon.json e reinicie o Docker. Todos os comandos “ docker pull ” vão tentar o espelho primeiro e, se ele não estiver disponível, vão tentar o Docker Hub.

Vários espelhos garantem redundância:

{
  "registry-mirrors": [
    "https://mirror1.company.com",
    "https://mirror2.company.com",
    "https://registry-1.docker.io"
  ]
}

O Docker vai tentar os espelhos em ordem até que um funcione.

A configuração do espelho do BuildKit precisa de uma configuração separada porque o BuildKit ignora algumas configurações do daemon:

# buildkitd.toml
debug = true

[registry."docker.io"]
  mirrors = ["mirror.company.com"]

[registry."mirror.company.com"]
  http = true
  insecure = true

Você pode começar o BuildKit com a configuração personalizada:

buildkitd --config=/etc/buildkit/buildkitd.toml

Ou use a configuração de espelho embutido do BuildKit:

docker buildx create \
  --name mybuilder \
  --config /etc/buildkit/buildkitd.toml \
  --use

Por fim, teste a configuração do espelho criando uma imagem que puxe do Docker Hub:

FROM python:3.13-slim
RUN pip install requests

docker build --progress=plain .

A bandeira ` --progress=plain ` mostra qual registro o BuildKit realmente entra em contato. Você deve ver os URLs do espelho na saída da compilação.

É isso aí!

Está lidando com configurações complexas de proxy com vários contêineres? O Docker Compose facilita a conexão em rede e a descoberta de serviços.

Reforço da segurança

As configurações de proxy abrem novas possibilidades de ataque que precisam de muita atenção. Veja como bloquear o acesso ao soquete do Docker e proteger as credenciais do proxy contra exposição.

Proxy de socket do Docker

Expor o socket do Docker diretamente cria um risco enorme de segurança.

O soquete do Docker (/var/run/docker.sock) dá acesso de nível raiz a todo o seu sistema host. Qualquer processo que possa gravar nesse soquete pode criar contêineres com acesso ao sistema de arquivos do host, aumentar privilégios ou sair completamente do isolamento do contêiner.

A montagem direta na tomada é perigosa:

# DON'T DO THIS
docker run -v /var/run/docker.sock:/var/run/docker.sock myapp

Esse padrão aparece em configurações Docker-in-Docker e pipelines CI/CD, mas é um pesadelo para a segurança. Um contêiner comprometido pode controlar todo o daemon do Docker.

Os serviços de proxy de soquete criam uma camada intermediária mais segura. Eles filtram as chamadas da API do Docker e limitam o que os contêineres podem realmente fazer.

Use o docker-socket-proxy da Tecnativa:

# docker-compose.yml
version: '3.8'
services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - CONTAINERS=1
      - IMAGES=1
      - NETWORKS=1
      - VOLUMES=1
      - BUILD=0
      - COMMIT=0
      - CONFIGS=0
      - SECRETS=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "2375:2375"

O proxy só mostra pontos finais específicos da API do Docker. Defina as variáveis de ambiente como 1 para operações permitidas e 0 para as bloqueadas.

As suas aplicações conectam-se ao proxy em vez de ao socket bruto:

docker run --env DOCKER_HOST=tcp://docker-proxy:2375 myapp

Aqui estão algumas estratégias adicionais para fortalecer os soquetes:

• Execute o proxy de soquete em um segmento de rede separado
• Use autenticação TLS entre os clientes e o proxy
• Fica de olho nos logs do proxy do soquete pra ver se tem alguma chamada de API suspeita.
• Troque as credenciais de acesso do proxy de vez em quando

Gerenciamento de credenciais

As credenciais de proxy em URLs de texto simples aparecem em todo o lado - registos, listas de processos, dumps de ambiente.

Nunca coloque credenciais em URLs proxy:

# SECURITY RISK - credentials visible in process list
export HTTP_PROXY=http://admin:password123@proxy.company.com:8080

Qualquer pessoa com acesso a ps aux ou dumps de variáveis de ambiente pode ver a sua senha de proxy. Isso inclui registros de aplicativos, inspeção de contêineres e ferramentas de monitoramento do sistema.

Em vez disso, use arquivos de autenticação:

# Create credentials file with restricted permissions
echo "admin:password123" > ~/.proxy-creds
chmod 600 ~/.proxy-creds

# Configure proxy without embedded credentials
export HTTP_PROXY=http://proxy.company.com:8080

Configure seu servidor proxy pra ler as credenciais do arquivo ou use sistemas de autenticação externos.

Os proxies TLS criptografam todo o tráfego do proxy, incluindo as trocas de autenticação:

# HTTPS proxy encrypts credentials in transit
export HTTPS_PROXY=https://proxy.company.com:8443

Configure seu servidor proxy com certificados TLS adequados - sejam eles de uma CA ou certificados autoassinados distribuídos para as máquinas clientes.

A autenticação por certificado acaba com as senhas:

# Client certificate authentication
export HTTPS_PROXY=https://proxy.company.com:8443
curl --cert client.crt --key client.key --cacert proxy-ca.crt https://example.com

O proxy verifica os certificados dos clientes em vez de usar nome de usuário e senha. Os certificados podem ser cancelados um por um se forem comprometidos.

O gerenciamento de segredos do Kubernetes mantém as credenciais de proxy fora das imagens de contêiner:

apiVersion: v1
kind: Secret
metadata:
  name: proxy-credentials
type: Opaque
data:
  username: YWRtaW4=  # base64 encoded
  password: cGFzc3dvcmQxMjM=  # base64 encoded

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: myapp
        env:
        - name: PROXY_USER
          valueFrom:
            secretKeyRef:
              name: proxy-credentials
              key: username
        - name: PROXY_PASS
          valueFrom:
            secretKeyRef:
              name: proxy-credentials
              key: password

Os segredos ficam criptografados em repouso e são injetados em tempo de execução sem aparecer nas camadas da imagem.

Bloqueie o acesso ao soquete e criptografe suas credenciais - seu futuro vai te agradecer.

Pensando em alternativas ao Docker para configurar seu proxy? Dá uma olhada no Docker e no Podman pra escolher a ferramenta de contêinerização certa pra você.

Resolução de problemas comuns

Problemas de proxy aparecem como tempos limite, falhas de conexão e erros de compilação misteriosos que funcionam bem fora da sua rede. Aqui está uma maneira legal de diagnosticar e resolver os problemas mais comuns do proxy do Docker.

Abordagem diagnóstica estruturada

Comece com o básico e vá avançando aos poucos.

Passo 1: Verifique a conexão do proxy a partir do host

Teste se o seu servidor proxy está acessível:

curl -x http://proxy.company.com:8080 https://registry-1.docker.io/v2/

Se isso não funcionar, tem algo errado com a configuração do seu proxy ou com o roteamento da sua rede. Fala com a galera da rede antes de tentar resolver os problemas do Docker.

Passo 2: Dá uma olhada nas configurações do proxy do daemon do Docker.

Dá uma olhada se o daemon tá lendo a configuração do seu proxy:

docker info | grep -i proxy

Você deve ver suas URLs proxy listadas. Se não estiverem lá, dá uma olhada em /etc/docker/daemon.json e reinicia o serviço Docker.

Passo 3: Teste as operações do cliente Docker

Tenta baixar uma imagem simples:

docker pull hello-world

Sucesso significa que as configurações de proxy do seu cliente estão funcionando. Falha indica problemas no proxy no nível do daemon.

Passo 4: Teste a conectividade no nível do contêiner

Execute um contêiner e teste as conexões de saída:

docker run --rm \
  -e HTTP_PROXY=http://proxy.company.com:8080 \
  -e HTTPS_PROXY=http://proxy.company.com:8080 \
  python:3.13-slim \
  python -c "import urllib.request; print(urllib.request.urlopen('https://pypi.org').getcode())"

Isso isola se o problema está nas operações do Docker ou na rede do contêiner.

Problemas comuns e soluções

Problema: O tempo limite do docker pull expirou

Você vai ver esse erro quando o Docker não conseguir acessar registros externos:

Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io: no such host

Comece testando a conectividade básica para ver onde tá o problema:

# Check if DNS resolution works through proxy
nslookup registry-1.docker.io

# Test direct registry access
curl -I https://registry-1.docker.io/v2/

# Verify daemon proxy configuration
sudo journalctl -u docker.service | grep -i proxy

Resolva isso verificando a configuração do DNS e do proxy:

• Adicionar servidores DNS a /etc/docker/daemon.json

• Configurar NO_PROXY para servidores DNS internos

• Verifique se o proxy suporta o método HTTPS CONNECT.

Problema: Falha na instalação do pacote durante a compilação

Os gerenciadores de pacotes dentro dos contêineres não conseguem acessar os repositórios, mostrando erros como este:

E: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/jammy/Release

Teste a conexão do gerenciador de pacotes direto em um contêiner temporário:

# Test package manager connectivity in a running container
docker run -it --rm python:3.13 bash
apt-get update -o Debug::Acquire::http=true

A saída detalhada mostra exatamente onde a conexão falhou.

Resolva isso configurando os gerenciadores de pacotes pra usar seu proxy:

• Configurar as definições do proxy do gerenciador de pacotes no Dockerfile
• Passar argumentos de compilação proxy para a compilação do Docker
• Verifique se o proxy bloqueia os domínios do repositório de pacotes.

Problema: O BuildKit não liga para as configurações de proxy

O BuildKit usa um jeito diferente de lidar com proxies do que o construtor antigo, causando erros como este:

failed to solve: failed to fetch remote https://github.com/user/repo.git

Teste se o problema é específico do BuildKit verificando a configuração do seu construtor:

# Check BuildKit configuration
docker buildx inspect

# Build with legacy builder
DOCKER_BUILDKIT=0 docker build .

Se o criador de legado funcionar, você tem um problema de configuração do proxy BuildKit.

Resolva os problemas de proxy do BuildKit com estas abordagens:

• Configure as configurações de proxy específicas do BuildKit em buildkitd.toml
• Use --build-arg para passar variáveis proxy explicitamente
• Desativar o BuildKit para compilações sensíveis a proxy

Problema: O contêiner não consegue acessar serviços externos

A sua aplicação dentro do contêiner não consegue se conectar às APIs externas:

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='api.example.com', port=443)

Tenta resolver isso testando a conexão de dentro do contêiner:

# Test from inside the container
docker exec container_name curl -v https://api.example.com

# Check container environment variables
docker exec container_name env | grep -i proxy

Isso mostra se as variáveis proxy estão presentes e se a tentativa de conexão deu certo.

Resolva os problemas de conectividade do contêiner garantindo que o proxy esteja configurado corretamente:

• Passar variáveis de ambiente proxy em tempo de execução
• Configurar as definições de proxy específicas da aplicação
• Adicionar destino à lista NO_PROXY

Análise de registros e testes de conectividade

Os logs do daemon do Docker mostram tudo sobre as negociações e falhas do proxy.

Em sistemas baseados em systemd, use journalctl para acompanhar os logs do serviço Docker em tempo real:

# SystemD systems
sudo journalctl -u docker.service -f

Para sistemas que usam arquivos de log tradicionais, dá uma olhada direto no log do Docker:

# Direct log file
sudo tail -f /var/log/docker.log

Procure por padrões específicos relacionados a proxy nos registros. Erros de conexão recusada indicam que o servidor proxy não está acessível. Falhas na autenticação aparecem como mensagens “407 Proxy Authentication Required” (Autenticação de proxy necessária). Erros de tempo limite indicam problemas de roteamento de rede ou sobrecarga do servidor proxy.

Testes em nível de contêiner com curl e wget te dão uma visão detalhada do comportamento do proxy.

Teste as conexões HTTP através do seu proxy para ver exatamente o que acontece durante o handshake:

# Test HTTP proxy
docker run --rm \
  -e HTTP_PROXY=http://proxy.company.com:8080 \
  python:3.13-slim \
  curl -v http://httpbin.org/ip

A saída detalhada mostra a resolução DNS, o estabelecimento da conexão proxy e o fluxo real da solicitação HTTP. Você vai ver linhas tipo “Conectado a proxy.company.com” seguidas de “CONNECT httpbin.org:80” se o túnel proxy estiver funcionando direitinho.

As conexões HTTPS precisam que o proxy suporte o método CONNECT:

# Test HTTPS proxy
docker run --rm \
  -e HTTPS_PROXY=http://proxy.company.com:8080 \
  python:3.13-slim \
  curl -v https://httpbin.org/ip

Fica de olho em “CONNECT httpbin.org:443 HTTP/1.1” na saída. Se você vir “Método não permitido” ou erros parecidos, seu proxy não aceita tunelamento HTTPS.

Teste a autenticação colocando as credenciais no URL do proxy:

# Test with authentication
docker run --rm \
  -e HTTPS_PROXY=http://user:pass@proxy.company.com:8080 \
  python:3.13-slim \
  wget -O- https://httpbin.org/ip

Falhas na autenticação aparecem como respostas “407 Proxy Authentication Required” (Autenticação de proxy necessária). A autenticação bem-sucedida vai direto para a solicitação de destino.

A depuração em nível de rede com o tcpdump captura os pacotes reais entre o Docker e o seu servidor proxy.

Execute o tcpdump para ver todo o tráfego que está indo pro seu proxy:

# Capture proxy traffic
sudo tcpdump -i any host proxy.company.com and port 8080

Essa captura de pacotes brutos mostra as tentativas de conexão, a transferência de dados e o encerramento da conexão. Procure o estabelecimento da conexão TCP (pacotes SYN/ACK) seguido pelo tráfego HTTP. Os tempos limite de conexão aparecem como pacotes SYN repetidos sem resposta.

O teste de resolução DNS elimina uma fonte comum de confusão com proxies.

Muitos problemas de proxy são, na verdade, problemas de DNS disfarçados. Teste a resolução DNS dentro dos contêineres:

# Test DNS inside containers  
docker run --rm python:3.13-slim nslookup registry-1.docker.io

Se isso não funcionar, o contêiner não vai conseguir resolver nomes de domínio. Tenta usar um servidor DNS público pra isolar o problema:

# Test with custom DNS
docker run --dns 8.8.8.8 --rm python:3.13-slim nslookup registry-1.docker.io

Os ambientes corporativos geralmente têm servidores DNS que só funcionam dentro da rede. Seu proxy pode precisar lidar com solicitações DNS, além do tráfego HTTP, ou talvez você precise configurar contêineres com servidores DNS específicos que funcionem através do seu proxy.

Trabalhe cada camada de forma sistemática e você vai achar a causa principal.

Procurando opções que possam lidar com proxies de maneira diferente? Temos um guia sobre alternativas ao Docker para você dar uma olhada no panorama completo das ferramentas de conteinerização em 2025.

Conclusão

A configuração do proxy do Docker não é só pra baixar imagens, mas também pra criar aplicativos em contêineres confiáveis e seguros em ambientes corporativos.

Mostrei como configurar as definições de proxy em quatro camadas diferentes: operações do cliente, processos daemon, tempo de execução do contêiner e operações de tempo de compilação. Cada camada tem uma função específica e precisa de uma configuração diferente, desde a importação de arquivos JSON e variáveis de ambiente até as configurações do gerenciador de pacotes e do BuildKit. Uma estratégia de proxy em camadas protege você contra pontos únicos de falha.

Quer saber mais sobre o Docker, a conteinerização e a segurança ? Dá uma olhada na nossa lista de cursos:

• Introdução ao Docker
• Docker intermediário
• Conceitos de conteinerização e virtualização
• Containerização e virtualização com Docker e Kubernetes
• Conceitos de DevOps
• Introdução ao Kubernetes