Proxy Docker: la guida completa per far funzionare i container dietro i firewall aziendali

La maggior parte delle reti enterprise usa proxy per monitorare e filtrare il traffico internet. Questo crea ostacoli quando Docker prova a scaricare le immagini dai registry. Incontrerai timeout di connessione, errori di autenticazione e build fallite che a casa funzionano. Questi problemi legati al proxy possono bloccare i team di sviluppo che non riescono ad accedere alle immagini di base necessarie.

La configurazione del proxy in Docker risolve questi problemi di connettività, migliora le prestazioni tramite caching e soddisfa i requisiti di sicurezza aziendali. Una volta configurati, i tuoi container scaricheranno le immagini a prescindere dalle restrizioni di rete.

In questo tutorial, ti guiderò nella configurazione del proxy per il demone Docker, nell'impostazione delle variabili d'ambiente per i container e nella gestione del proxy in Docker Compose.

Nuovo a Docker e sommerso da tutti i concetti di rete? Inizia dalle basi di Docker e fai pratica passo dopo passo.

Capire l'architettura del proxy in Docker

Parti diverse dell'ecosistema Docker richiedono configurazioni proxy a livelli differenti.

I proxy agiscono da intermediari tra i componenti Docker e le reti esterne. Quando Docker deve scaricare immagini, i container hanno bisogno di accesso a internet o le build richiedono risorse esterne, i proxy controllano e monitorano queste connessioni. Si posizionano tra le tue applicazioni containerizzate e il mondo esterno, filtrando richieste e risposte.

Le organizzazioni usano proxy con Docker per prestazioni, sicurezza e compliance.

Le prestazioni migliorano grazie al caching di risorse usate di frequente come le immagini base, riducendo i tempi di download per tutto il team. I benefici in termini di sicurezza includono filtraggio del traffico, scansione malware e blocco dell'accesso a siti non autorizzati. I requisiti di compliance impongono che tutto il traffico di rete passi attraverso canali monitorati con controlli di accesso adeguati e audit trail.

La configurazione del proxy in Docker avviene su quattro livelli:

• Proxy client: influisce sui comandi della CLI Docker come docker pull e docker push

• Proxy del demone: controlla come il demone Docker accede ai registry esterni  

• Proxy a runtime del container: imposta le variabili proxy per le applicazioni dentro i container

• Proxy in fase di build: gestisce le impostazioni proxy durante le operazioni docker build quando i Dockerfile hanno bisogno di accesso a internet

Ogni livello ha uno scopo e richiede un proprio approccio di configurazione.

Capire il networking di Docker parte dal comprendere come comunicano i container. 

Configurare Docker per usare un proxy

Per far funzionare Docker con il proxy aziendale devi configurare sia il demone Docker sia il client.

Perché? Perché gestiscono tipi diversi di richieste di rete. 

Il demone gestisce pull, push e autenticazione ai registry, mentre il client gestisce le operazioni della CLI e le chiamate API. Se manca una delle due configurazioni, restano buchi dove le operazioni Docker possono fallire con errori di connessione.

Come configurare il demone Docker

Il demone Docker legge le impostazioni del proxy da /etc/docker/daemon.json. Crea questo file se non esiste:

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

Il campo noProxy elenca gli indirizzi che devono bypassare il proxy. Includi qui i domini dei tuoi registry interni e gli indirizzi localhost.

Impostare gli override del servizio systemd

Sui sistemi Linux basati su systemd, devi anche configurare il servizio Docker stesso per usare il proxy. Crea la directory di override e il file di configurazione:

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

Poi aggiungi queste variabili d'ambiente al file 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"Offerto da

Questo garantisce che il processo del demone Docker possa raggiungere i servizi esterni attraverso il proxy.

Docker non applicherà le modifiche al proxy finché non riavvii il demone. Esegui questi comandi per ricaricare systemd e riavviare Docker:

sudo systemctl daemon-reload
sudo systemctl restart dockerOfferto da

Il reload del demone indica a systemd di leggere la nuova configurazione del servizio, mentre il riavvio di Docker applica le modifiche al daemon.json.

Considerazioni specifiche per piattaforma

Docker Desktop gestisce la configurazione del proxy in modo diverso rispetto alle installazioni server. Su Windows e macOS, usa la GUI di Docker Desktop per impostare il proxy nella sezione Resources - Proxies. Queste impostazioni configurano automaticamente sia il demone che il client.

Gli host Linux che usano Docker Engine richiedono la configurazione manuale descritta sopra. Alcune distribuzioni impacchettano Docker in modo diverso, quindi verifica se il tuo sistema usa dockerd direttamente o tramite un altro service manager.

Verificare la configurazione

Verifica che Docker raggiunga i registry esterni con un semplice comando di pull:

docker pull hello-worldOfferto da

Puoi anche controllare la configurazione effettiva del demone:

docker system info | grep -i proxyOfferto da

Questo mostra se Docker ha rilevato e applicato le impostazioni del proxy.

Se i pull falliscono ancora, controlla i log del proxy per confermare che Docker instradi correttamente le richieste.

Problemi di networking ti bloccano? Esporre correttamente le porte Docker evita mal di testa di connettività.

Impostare le variabili d'ambiente del proxy

I comandi della CLI Docker richiedono una loro configurazione proxy separata da quella del demone. Le variabili d'ambiente ti danno un controllo flessibile su come i client Docker si connettono attraverso i proxy aziendali.

I proxy del client controllano operazioni della CLI come docker pull, docker push e docker login. Quando esegui questi comandi, il client Docker effettua richieste HTTP ai registry e deve sapere quale server proxy usare. Senza impostazioni proxy lato client, queste operazioni falliscono anche quando il demone è configurato correttamente.

Metodo di configurazione JSON

L'approccio più pulito usa il file di configurazione di Docker in ~/.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"
    }
  }
}Offerto da

Questo metodo mantiene le impostazioni del proxy all'interno della configurazione di Docker e non influenza altre applicazioni sul sistema.

Alternativa con variabili d'ambiente

Puoi anche impostare le classiche variabili d'ambiente del proxy che Docker rileverà automaticamente usando questi comandi:

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.comOfferto da

Queste variabili funzionano per qualsiasi applicazione che rispetti gli standard proxy, non solo Docker.

Configurazione globale vs per utente

Per la configurazione a livello di sistema, aggiungi le variabili d'ambiente in /etc/environment o crea uno script in /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.comOfferto da

Per la configurazione per singolo utente, aggiungile al profilo della tua shell (~/.bashrc, ~/.zshrc) oppure usa il metodo con config JSON. Le impostazioni per utente danno ai developer la flessibilità di usare proxy diversi o bypassarli del tutto per i test.

Considerazioni di sicurezza

Non dovresti mai hardcodare username e password nei file di configurazione o nelle variabili d'ambiente. 

Le credenziali del proxy in chiaro creano rischi di sicurezza, soprattutto in ambienti condivisi o in sistemi di controllo versione.

Invece, usa questi approcci:

• Configura il proxy per l'autenticazione basata su IP quando possibile
• Usa credential helper o sistemi di archiviazione sicura per l'autenticazione
• Imposta account di servizio con permessi minimi per le operazioni Docker

Se devi includere credenziali, usa il formato http://username:[email protected]:8080, ma archivia questi dati in file protetti con permessi ristretti.

Configurazione del proxy in fase di build

Le build Docker hanno bisogno che le impostazioni proxy vengano passate esplicitamente tramite argomenti di build:

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 .Offerto da

Gli argomenti di build diventano variabili d'ambiente all'interno del contesto di build.

Questo permette alle istruzioni RUN di scaricare pacchetti e dipendenze attraverso il proxy. Senza questi argomenti, le build falliscono quando i Dockerfile cercano di installare software o recuperare risorse da internet.

Le impostazioni proxy in fase di build non persistono nell'immagine finale a meno che tu non le imposti esplicitamente con istruzioni ENV nel tuo Dockerfile.

Le variabili d'ambiente ti danno la flessibilità di gestire le impostazioni proxy al livello giusto per il tuo workflow.

Gli argomenti di build ti confondono? Padroneggia i build args di Docker con esempi reali che funzionano davvero.

Injection del proxy a runtime e in fase di build

La configurazione del client Docker ti porta solo a metà strada: i tuoi container e le build hanno bisogno di impostazioni proxy proprie. In questa sezione, ti mostro come iniettare la configurazione del proxy a runtime e in fase di build.

Variabili d'ambiente a runtime

I container non ereditano le impostazioni proxy dell'host.

Devi passare esplicitamente le variabili del proxy quando avvii i container. Docker ti offre vari modi per farlo, a seconda che tu voglia configurare tutti i container o solo alcuni specifici.

La configurazione JSON è l'approccio più pulito per impostazioni proxy consistenti, come discusso prima. In sintesi, aggiungi questo al tuo ~/.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"
    }
  }
}Offerto da

Docker inietta automaticamente queste variabili in ogni container che avvii. Nessun flag aggiuntivo necessario.

I flag della CLI ti danno più controllo per singolo container:

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 \
  nginxOfferto da

Puoi anche passare un intero file di ambiente:

# 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 nginxOfferto da

Ai container esistenti si possono iniettare variabili proxy dopo l'avvio usando docker exec:

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

Questo approccio funziona per comandi una tantum ma non persiste ai riavvii del container.

Configurazione del proxy in fase di build

Le build di immagini falliscono in ambienti con proxy a meno che tu non passi esplicitamente le impostazioni del proxy.

Gli argomenti di build sono il modo standard per iniettare variabili proxy durante le build:

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 .Offerto da

Il tuo Dockerfile deve dichiarare questi argomenti per usarli:

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Usa il proxy per l'installazione dei pacchetti
RUN apt-get update && apt-get install -y curl

# Non persistere il proxy nell'immagine finaleOfferto da

Le dichiarazioni nel Dockerfile ti permettono di impostare valori predefiniti per il 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 requestsOfferto da

L'istruzione ENV rende le variabili del proxy disponibili a tutti i successivi comandi RUN nella tua build.

Tieni presente che limitazioni di BuildKit possono causare problemi di proxy con le versioni Docker più recenti. BuildKit fa caching aggressivo dei contesti di build, a volte ignorando le modifiche al proxy.

Puoi forzare BuildKit a riconoscere gli aggiornamenti del proxy:

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

Oppure puoi disabilitare del tutto BuildKit per build sensibili al proxy:

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

Per quanto riguarda le multi-stage build, serve una configurazione proxy coerente in tutti gli stage:

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

# Pulisci le variabili proxy nell'immagine finale
ENV HTTP_PROXY=
ENV HTTPS_PROXY=
ENV NO_PROXY=Offerto da

Ogni stage eredita gli argomenti di build ma non le variabili d'ambiente dagli stage precedenti. Imposta le variabili del proxy esplicitamente in ogni stage che ne ha bisogno.

In breve: configura una volta, inietta ovunque.

Hai dubbi tra ENTRYPOINT e CMD nei container con proxy? Ecco la guida completa con esempi pratici.

Configurare i gestori di pacchetti per usare un proxy nei container

Le impostazioni proxy di Docker non si propagano automaticamente ai gestori di pacchetti dentro i container. Devi configurare ogni gestore di pacchetti separatamente per scaricare i pacchetti tramite il proxy aziendale.

Gestori come apt-get, yum e apk effettuano connessioni HTTP dirette ai repository. In ambienti con rete ristretta, queste connessioni falliscono a meno che il gestore di pacchetti non conosca il tuo server proxy.

Le variabili d'ambiente standard non bastano. La maggior parte dei gestori ha file di configurazione propri che prevalgono sulle impostazioni proxy di sistema.

Ubuntu/Debian: configurazione di apt-get

Crea un file di configurazione del proxy che apt-get leggerà durante l'installazione dei pacchetti.

Aggiungi questo al tuo Dockerfile:

FROM python:3.13

# Configura il proxy per apt
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 wgetOfferto da

Il file /etc/apt/apt.conf.d/proxy.conf indica ad apt-get di instradare tutti i download dei pacchetti attraverso il proxy. Il file persiste tra i comandi RUN nella tua build.

Puoi anche impostare esclusioni dal proxy per repository interni:

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

Alpine Linux: configurazione di apk

Alpine usa il gestore pacchetti apk, che legge le impostazioni proxy da /etc/apk/repositories e dalle variabili d'ambiente.

FROM python:3.13-alpine

# Configura il proxy per apk
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080

RUN apk add --no-cache curl wgetOfferto da

Il apk di Alpine rispetta le variabili d'ambiente standard per l'HTTP proxy, quindi non servono file di configurazione separati. Ma puoi crearne uno per maggior controllo:

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

CentOS/RHEL: configurazione di yum

I sistemi CentOS e RHEL usano yum o dnf, che leggono le impostazioni proxy da /etc/yum.conf.

FROM centos:8

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

RUN yum update -y && yum install -y curl wgetOfferto da

Per le versioni più recenti di CentOS che usano dnf, usa quanto segue:

FROM centos:stream9

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

RUN dnf update -y && dnf install -y curl wgetOfferto da

Puoi anche escludere domini specifici dall'instradamento tramite proxy aggiungendo questo comando:

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

Testare il funzionamento del proxy

Per prima cosa, verifica che il tuo gestore di pacchetti raggiunga i repository attraverso il proxy.

Aggiungi comandi di test al tuo Dockerfile:

FROM python:3.13

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

# Test della connettività del gestore pacchetti
RUN apt-get update && \
    apt-get install -y --dry-run curl && \
    echo "Package manager proxy test passed"

# Installa i pacchetti reali
RUN apt-get install -y curl python3-pipOfferto da

Il flag --dry-run testa la risoluzione dei pacchetti senza installare nulla. Se ha successo, la tua configurazione proxy funziona.

Puoi anche testare con output verboso per fare debug dei problemi di connessione:

RUN apt-get -o Debug::Acquire::http=true updateOfferto da

Questo mostra esattamente quali URL prova ad accedere apt-get e se le connessioni tramite proxy vanno a buon fine.

Per i test su Alpine, usa quanto segue:

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

Ricapitolando: configura ogni gestore di pacchetti singolarmente, e le tue build funzioneranno dietro qualsiasi proxy.

Devi ripulire artefatti di build legati al proxy? I comandi Docker prune liberano spazio e mantengono il sistema pulito.

Implementazioni proxy avanzate

I proxy HTTP di base sono un inizio, ma gli ambienti di produzione necessitano di maggior controllo su accesso ai registry e caching delle immagini. Ecco come impostare proxy con caching e mirror dei registry per migliorare prestazioni e affidabilità.

Registry proxy con caching

Scaricare ripetutamente le stesse immagini base spreca banda e rallenta le build.

I proxy con caching si posizionano tra i client Docker e registry esterni come Docker Hub. Memorizzano localmente le immagini più richieste, così i pull successivi arrivano dalla rete interna invece che da internet.

La scelta più diffusa in ambienti enterprise è Harbor:

# docker-compose.yml per 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.confOfferto da

Puoi configurare Harbor come proxy cache modificando 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-tokenOfferto da

Se ti serve un'alternativa più semplice per un caching di base, usa Docker Registry Proxy. Ecco come:

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:2Offerto da

Poi punta i tuoi client Docker al proxy con caching:

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

Ecco tutti i vantaggi che ottieni con i proxy con caching:

• Pull più veloci dopo il primo download
• Minore utilizzo di banda internet
• Migliore affidabilità delle build quando i registry esterni hanno problemi
• Controllo accessi centralizzato e scansione delle immagini

Mirror dei registry e BuildKit

I mirror dei registry ti permettono di reindirizzare i pull verso registry interni o geograficamente più vicini.

Una configurazione con singolo mirror instrada tutte le richieste a Docker Hub attraverso un mirror:

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

Aggiungi questo a /etc/docker/daemon.json e riavvia Docker. Tutti i comandi docker pull proveranno prima il mirror, tornando a Docker Hub se il mirror non è disponibile.

Più mirror forniscono ridondanza:

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

Docker proverà i mirror in ordine finché uno non risponde.

La configurazione dei mirror con BuildKit richiede impostazioni separate perché BuildKit bypassa alcune impostazioni del demone:

# buildkitd.toml
debug = true

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

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

Puoi avviare BuildKit con la configurazione personalizzata:

buildkitd --config=/etc/buildkit/buildkitd.tomlOfferto da

Oppure usare la configurazione inline dei mirror di BuildKit:

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

Infine, testa la configurazione del mirror costruendo un'immagine che scarica da Docker Hub:

FROM python:3.13-slim
RUN pip install requestsOfferto da

docker build --progress=plain .Offerto da

Il flag --progress=plain mostra quale registry contatta effettivamente BuildKit. Dovresti vedere gli URL dei tuoi mirror nell'output della build.

È tutto!

Gestisci setup proxy complessi multi-container? Docker Compose semplifica networking e service discovery.

Hardening della sicurezza

Le configurazioni proxy aprono nuove superfici d'attacco che richiedono attenzione. Ecco come limitare l'accesso al socket Docker e proteggere le credenziali del proxy da esposizioni.

Proxy del socket Docker

Esporre direttamente il socket di Docker crea un enorme rischio di sicurezza.

Il socket di Docker (/var/run/docker.sock) fornisce accesso a livello root all'intero host. Qualsiasi processo che può scrivere su questo socket può avviare container con accesso al filesystem dell'host, aumentare i privilegi o uscire completamente dall'isolamento dei container.

Montare direttamente il socket è pericoloso:

# NON FARLO
docker run -v /var/run/docker.sock:/var/run/docker.sock myappOfferto da

Questo pattern compare in setup Docker-in-Docker e pipeline CI/CD, ma è un incubo di sicurezza. Un container compromesso può controllare l'intero demone Docker.

I servizi di socket proxy creano un livello intermedio più sicuro. Filtrano le chiamate all'API di Docker e limitano cosa possono fare i container.

Usa il docker-socket-proxy di 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"Offerto da

Il proxy espone solo specifici endpoint dell'API Docker. Imposta le variabili d'ambiente a 1 per le operazioni consentite e a 0 per quelle bloccate.

Le tue applicazioni si connettono al proxy invece che al socket grezzo:

docker run --env DOCKER_HOST=tcp://docker-proxy:2375 myappOfferto da

Ecco ulteriori strategie per mettere in sicurezza il socket:

• Esegui il socket proxy su un segmento di rete separato
• Usa l'autenticazione TLS tra client e proxy
• Monitora i log del socket proxy per chiamate API sospette
• Ruota regolarmente le credenziali di accesso al proxy

Gestione delle credenziali

Le credenziali del proxy in URL in chiaro compaiono ovunque: log, liste di processi, dump delle variabili d'ambiente.

Non inserire mai credenziali direttamente negli URL del proxy:

# RISCHIO DI SICUREZZA - credenziali visibili nella lista processi
export HTTP_PROXY=http://admin:[email protected]:8080Offerto da

Chiunque abbia accesso a ps aux o ai dump delle variabili d'ambiente può vedere la tua password del proxy. Questo include log applicativi, ispezione dei container e strumenti di monitoraggio di sistema.

Usa invece file di autenticazione:

# Crea file di credenziali con permessi ristretti
echo "admin:password123" > ~/.proxy-creds
chmod 600 ~/.proxy-creds

# Configura il proxy senza credenziali nell'URL
export HTTP_PROXY=http://proxy.company.com:8080Offerto da

Configura il server proxy per leggere le credenziali dal file o usa sistemi di autenticazione esterni.

I proxy TLS cifrano tutto il traffico proxy, inclusi gli handshake di autenticazione:

# Il proxy HTTPS cifra le credenziali in transito
export HTTPS_PROXY=https://proxy.company.com:8443Offerto da

Configura il tuo server proxy con certificati TLS adeguati, da una CA o certificati self-signed distribuiti alle macchine client.

L'autenticazione basata su certificati elimina completamente le password:

# Autenticazione con certificato client
export HTTPS_PROXY=https://proxy.company.com:8443
curl --cert client.crt --key client.key --cacert proxy-ca.crt https://example.comOfferto da

Il proxy valida i certificati client invece di combinazioni username/password. I certificati possono essere revocati singolarmente in caso di compromissione.

La gestione dei secret in Kubernetes mantiene le credenziali del proxy fuori dalle immagini dei container:

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

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: passwordOfferto da

I secret restano cifrati a riposo e vengono iniettati a runtime senza comparire nei layer dell'immagine.

Metti in sicurezza l'accesso al socket e cifra le credenziali: te ne ringrazierai in futuro.

Stai valutando alternative a Docker per il tuo setup proxy? Confronta Docker e Podman per scegliere lo strumento di containerizzazione giusto.

Risoluzione dei problemi comuni

I problemi di proxy si manifestano come timeout, fallimenti di connessione ed errori di build misteriosi che fuori dalla tua rete funzionano. Ecco un approccio sistematico per diagnosticare e correggere i problemi più comuni del proxy in Docker.

Approccio diagnostico strutturato

Parti dalle basi e sali lungo lo stack.

Passo 1: verifica la connettività al proxy dall'host

Testa se il tuo server proxy è raggiungibile:

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

Se fallisce, ci sono problemi nella configurazione del proxy o nel routing della rete. Contatta il tuo team di rete prima di fare troubleshooting su Docker.

Passo 2: controlla le impostazioni proxy del demone Docker

Verifica che il demone legga la tua configurazione del proxy:

docker info | grep -i proxyOfferto da

Dovresti vedere gli URL del proxy elencati. Se mancano, controlla /etc/docker/daemon.json e riavvia il servizio Docker.

Passo 3: testa le operazioni del client Docker

Prova a fare il pull di un'immagine semplice:

docker pull hello-worldOfferto da

Se ha successo, le impostazioni proxy del client funzionano. In caso di errore, il problema è probabilmente a livello di demone.

Passo 4: testa la connettività a livello di container

Esegui un container e testa le connessioni in uscita:

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())"Offerto da

Questo isola se il problema riguarda le operazioni di Docker o il networking dei container.

Problemi comuni e soluzioni

Problema: docker pull va in timeout

Vedrai questo errore quando Docker non riesce a raggiungere i registry esterni:

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

Inizia testando la connettività di base per isolare dove si verifica il problema:

# Verifica se la risoluzione DNS funziona tramite proxy
nslookup registry-1.docker.io

# Test accesso diretto al registry
curl -I https://registry-1.docker.io/v2/

# Verifica configurazione proxy del demone
sudo journalctl -u docker.service | grep -i proxyOfferto da

Risolvi affrontando i problemi di DNS e configurazione del proxy:

• Aggiungi server DNS a /etc/docker/daemon.json

• Configura NO_PROXY per i server DNS interni

• Controlla che il proxy supporti il metodo HTTPS CONNECT

Problema: l'installazione dei pacchetti fallisce durante le build

I gestori di pacchetti dentro i container non raggiungono i repository, mostrando errori come questo:

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

Testa la connettività del gestore di pacchetti direttamente in un container temporaneo:

# Test connettività del gestore pacchetti in un container in esecuzione
docker run -it --rm python:3.13 bash
apt-get update -o Debug::Acquire::http=trueOfferto da

L'output verboso mostra esattamente dove fallisce la connessione.

Risolvi configurando i gestori di pacchetti per usare il proxy:

• Configura le impostazioni proxy del gestore pacchetti nel Dockerfile
• Passa gli argomenti di build del proxy alla build di Docker
• Controlla se il proxy blocca i domini dei repository di pacchetti

Problema: BuildKit ignora le impostazioni del proxy

BuildKit gestisce il proxy in modo diverso rispetto al builder legacy e fa caching aggressivo dei contesti di build, causando errori come questo:

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

Verifica se il problema è specifico di BuildKit controllando la configurazione del builder:

# Controlla la configurazione di BuildKit
docker buildx inspect

# Build con builder legacy
DOCKER_BUILDKIT=0 docker build .Offerto da

Se il builder legacy funziona, hai un problema di configurazione del proxy in BuildKit.

Risolvi i problemi di proxy con BuildKit con questi approcci:

• Configura impostazioni proxy specifiche per BuildKit in buildkitd.toml
• Usa --build-arg per passare esplicitamente le variabili del proxy
• Disabilita BuildKit per build sensibili al proxy

Problema: il container non riesce a raggiungere servizi esterni

La tua applicazione dentro il container non riesce a connettersi ad API esterne:

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

Fai debug testando la connettività dall'interno del container:

# Test dall'interno del container
docker exec container_name curl -v https://api.example.com

# Controlla le variabili d'ambiente del container
docker exec container_name env | grep -i proxyOfferto da

Questo mostra se le variabili del proxy sono presenti e se il tentativo di connessione riesce.

Risolvi i problemi di connettività del container assicurando una corretta configurazione del proxy:

• Passa le variabili del proxy a runtime
• Configura impostazioni proxy specifiche per l'applicazione
• Aggiungi la destinazione alla lista NO_PROXY

Analisi dei log e test di connettività

I log del demone Docker rivelano la storia completa delle negoziazioni e dei fallimenti del proxy.

Sui sistemi basati su systemd, usa journalctl per seguire in tempo reale i log del servizio Docker:

# Sistemi SystemD
sudo journalctl -u docker.service -fOfferto da

Per sistemi che usano log tradizionali, controlla direttamente il log di Docker:

# File di log diretto
sudo tail -f /var/log/docker.logOfferto da

Cerca pattern specifici legati al proxy nei log. Gli errori di connessione rifiutata indicano che il server proxy non è accessibile. I fallimenti di autenticazione compaiono come messaggi "407 Proxy Authentication Required". I timeout suggeriscono problemi di routing di rete o sovraccarico del proxy.

Test a livello di container con curl e wget ti danno visibilità dettagliata sul comportamento del proxy.

Testa le connessioni HTTP tramite il proxy per vedere esattamente cosa succede durante l'handshake:

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

L'output verboso mostra la risoluzione DNS, la stabilizzazione della connessione al proxy e il flusso della richiesta HTTP. Vedrai righe come "Connected to proxy.company.com" seguite da "CONNECT httpbin.org:80" se il tunnel del proxy funziona correttamente.

Le connessioni HTTPS richiedono che il proxy supporti il metodo CONNECT:

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

Cerca "CONNECT httpbin.org:443 HTTP/1.1" nell'output. Se vedi "Method not allowed" o errori simili, il tuo proxy non supporta il tunneling HTTPS.

Testa l'autenticazione inserendo le credenziali nell'URL del proxy:

# Test con autenticazione
docker run --rm \
  -e HTTPS_PROXY=http://user:[email protected]:8080 \
  python:3.13-slim \
  wget -O- https://httpbin.org/ipOfferto da

I fallimenti di autenticazione compaiono come risposte "407 Proxy Authentication Required". Un'autenticazione riuscita procede direttamente alla richiesta di destinazione.

Debug a livello di rete con tcpdump cattura i pacchetti reali tra Docker e il server proxy.

Esegui tcpdump per vedere tutto il traffico diretto al proxy:

# Cattura il traffico del proxy
sudo tcpdump -i any host proxy.company.com and port 8080Offerto da

Questa cattura grezza dei pacchetti mostra tentativi di connessione, trasferimento dati e terminazione della connessione. Cerca l'instaurazione della connessione TCP (pacchetti SYN/ACK) seguita da traffico HTTP. I timeout appaiono come pacchetti SYN ripetuti senza risposta.

Test della risoluzione DNS elimina una fonte comune di confusione sul proxy.

Molti problemi di proxy sono in realtà problemi DNS mascherati. Testa la risoluzione DNS dentro i container:

# Test DNS dentro i container  
docker run --rm python:3.13-slim nslookup registry-1.docker.ioOfferto da

Se fallisce, il container non riesce a risolvere i nomi di dominio. Prova a usare un DNS pubblico per isolare il problema:

# Test con DNS personalizzato
docker run --dns 8.8.8.8 --rm python:3.13-slim nslookup registry-1.docker.ioOfferto da

Gli ambienti aziendali spesso hanno server DNS che funzionano solo dall'interno della rete. Il tuo proxy potrebbe dover gestire sia le richieste DNS sia il traffico HTTP, oppure potresti dover configurare i container con server DNS specifici che funzionano tramite il proxy.

Lavora sistematicamente su ogni livello e troverai la causa radice.

Cerchi opzioni che possano gestire i proxy in modo differente? Abbiamo una guida sulle alternative a Docker per esplorare l'intero panorama attuale degli strumenti di containerizzazione nel 2025.

Conclusione

La configurazione del proxy in Docker non serve solo a far scaricare le immagini: è anche fondamentale per costruire applicazioni containerizzate affidabili e sicure negli ambienti enterprise.

Ti ho mostrato come configurare il proxy su quattro livelli diversi: operazioni del client, processi del demone, runtime del container e operazioni in fase di build. Ogni livello ha uno scopo specifico e richiede un proprio approccio di configurazione, dai file JSON e variabili d'ambiente alle impostazioni dei gestori di pacchetti e configurazioni di BuildKit. Una strategia a livelli per il proxy ti protegge da singoli punti di guasto.

Vuoi approfondire Docker, la containerizzazione e la sicurezza? Dai un'occhiata alla nostra lista di corsi selezionati:

• Introduction to Docker
• Intermediate Docker
• Containerization and Virtualization Concepts
• Containerization and Virtualization with Docker and Kubernetes
• DevOps Concepts
• Introduction to Kubernetes