Configuration du proxy Docker et SOCKS5 : démon, build, conteneurs et ponts

Si vous recherchez un « configurateur socks5 » parce que les pulls Docker ne cessent de expirer, vous n'êtes pas seul. Docker a au moins trois couches de proxy, et elles ne partagent pas les paramètres. Un proxy qui fonctionne pour docker pull peut ne pas aider apt-get à l'intérieur d'un build, et SOCKS5 — courant sur de nombreux services proxy — n'est pas accepté par les variables de proxy du démon Docker. Ce guide parcourt chaque couche avec une configuration copier-coller et des étapes de vérification, afin que vous puissiez router uniquement ce qui doit être routé et éviter les fuites de DNS ou d'identifiants.

Les trois couches de proxy Docker (et où chacune s'applique)

Couche	Ce que cela affecte	Où le définir	Prise en charge du protocole
Démon	docker pull, docker push, authentification du registre	drop-in systemd (Linux) ou paramètres Docker Desktop	URL de proxy HTTP/HTTPS
Build	Commandes RUN pendant docker build (apt, pip, npm)	--build-arg + ARG dans le Dockerfile	URL de proxy HTTP/HTTPS
Runtime de conteneur	Trafic de votre application à l'intérieur du conteneur	options -e ou environment de Compose	Dépend de l'application (HTTP, HTTPS, SOCKS5 si l'application le prend en charge)

Un quatrième endroit que les gens oublient : le propre gestionnaire de paquets et les outils de l'hôte. Si vous ne pouvez pas atteindre le registre Docker, vous ne pouvez généralement pas non plus atteindre apt ou pip sur l'hôte. Définissez d'abord un proxy au niveau de l'hôte, puis configurez Docker. Pour un routage par application sur l'hôte, consultez notre guide du configurateur SOCKS5 pour les navigateurs, SSH, curl, git et Python.

Proxy au niveau du démon : pour tirer des images et communiquer avec les registres

Le démon Docker lit les variables d'environnement de proxy standard à partir de son service systemd. Créez un fichier drop-in :

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null <<'EOF'
[Service]
Environment=HTTP_PROXY=http://user:[email protected]:3128
Environment=HTTPS_PROXY=http://user:[email protected]:3128
Environment=NO_PROXY=localhost,127.0.0.1,::1,.internal.example,registry.internal.example
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Remarques :

• La valeur est l'URL du proxy. Pour un proxy HTTP standard qui prend en charge CONNECT, utilisez http://. Si votre point de terminaison proxy est lui-même encapsulé dans TLS, utilisez https://.
• NO_PROXY doit inclure tout registre interne ou hôte que vous ne voulez pas proxifier. Le point de tête dans .internal.example correspond aux sous-domaines dans de nombreuses implémentations, mais le comportement varie.
• Les identifiants dans le fichier systemd sont visibles par root. Pour les machines partagées, envisagez un redirecteur local qui ne nécessite pas d'identifiants dans l'environnement.

Vérifiez :

docker info | grep -i -A2 'Proxy'

Vous devriez voir les lignes HTTP Proxy, HTTPS Proxy et No Proxy. Si elles sont vides, le démon n'a pas pris en compte le drop-in.

Ensuite, testez un pull :

docker pull alpine:latest

Si cela échoue encore, vérifiez les journaux du démon :

journalctl -u docker.service --no-pager -n 50

Docker Desktop (macOS/Windows) dispose d'un paramètre de proxy GUI sous Paramètres, Ressources, Proxies. Il écrit les mêmes variables pour le démon.

Proxy au moment du build : quand le pull fonctionne mais pas RUN apt-get

Le proxy du démon ne s'applique pas automatiquement aux conteneurs de build. Vous devez passer des arguments de proxy et les déclarer dans le Dockerfile.

FROM debian:bookworm-slim

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*

Build :

docker build --build-arg HTTP_PROXY=http://user:[email protected]:3128 --build-arg HTTPS_PROXY=http://user:[email protected]:3128 --build-arg NO_PROXY=localhost,127.0.0.1 -t myapp .

Important : les valeurs de --build-arg peuvent être visibles dans l'historique de l'image et les journaux de build. Ne jamais intégrer d'identifiants dans une image finale. Utilisez des builds multi-étapes et désactivez les arguments avant l'étape finale, ou utilisez les montages secrets de BuildKit pour les identifiants.

Proxy par conteneur : définir les variables d'environnement à l'exécution

Pour les applications qui lisent les variables d'environnement de proxy, définissez-les lorsque vous démarrez le conteneur :

docker run --rm -e HTTP_PROXY=http://proxy.example:3128 -e HTTPS_PROXY=http://proxy.example:3128 -e NO_PROXY=localhost,127.0.0.1 myapp

Dans Docker Compose :

services:
  app:
    image: myapp
    environment:
      HTTP_PROXY: http://proxy.example:3128
      HTTPS_PROXY: http://proxy.example:3128
      NO_PROXY: localhost,127.0.0.1,.internal.example

Toutes les applications ne respectent pas ces variables. Certaines ne lisent que http_proxy en minuscules, d'autres ignorent complètement NO_PROXY, et certaines ont leur propre fichier de configuration. Vérifiez toujours la documentation de l'application.

SOCKS5 : pourquoi les variables de proxy de Docker ne l'acceptent pas

Le démon Docker et les variables de proxy --build-arg attendent des URL de proxy HTTP ou HTTPS. socks5:// n'est pas un schéma pris en charge pour le démon. Si votre service proxy ne vous donne qu'un point de terminaison SOCKS5, vous avez trois options pratiques :

1. Exécutez un pont local HTTP-vers-SOCKS5. Un petit redirecteur écoute sur 127.0.0.1:3128 et transmet à votre proxy SOCKS5. Ensuite, pointez le HTTP_PROXY de Docker vers le pont. Cela garde les identifiants SOCKS5 hors de l'environnement Docker.
2. Utilisez le transfert dynamique SSH plus un pont. ssh -D 1080 vous donne un proxy SOCKS5 local ; le pont le convertit en HTTP pour Docker. Cela fonctionne bien lorsque vous avez déjà un accès SSH à un hôte distant.
3. Configurez l'application à l'intérieur du conteneur pour utiliser SOCKS5 directement. De nombreux outils (curl, requests, git) prennent en charge socks5h:// nativement. Cela contourne complètement les paramètres de proxy de Docker et n'affecte que cette application.

Exemple : tester SOCKS5 depuis l'intérieur d'un conteneur sans pont, en utilisant curl. Sur Linux, ajoutez --add-host=host.docker.internal:host-gateway pour que le conteneur puisse atteindre un proxy s'exécutant sur l'hôte.

docker run --rm --add-host=host.docker.internal:host-gateway curlimages/curl:latest --socks5-hostname host.docker.internal:1080 https://ifconfig.me

--socks5-hostname envoie le nom d'hôte au proxy pour la résolution DNS, ce qui évite les fuites DNS. Si vous utilisez --socks5, curl résout le DNS localement et ne tunnelise que la connexion TCP — une source courante de géolocalisation incorrecte et de fuites.

Pour le code d'application, le schéma socks5h est souvent plus clair :

curl --proxy socks5h://user:[email protected]:1080 https://ifconfig.me

Vérifier que le proxy est réellement utilisé (et détecter les fuites)

• Démon : docker info | grep -i proxy affiche les variables. Ensuite, docker pull devrait passer par le proxy. Vous pouvez également vérifier les journaux du proxy pour une requête CONNECT vers registry-1.docker.io:443.
• Build : Ajoutez une étape RUN qui affiche l'IP observée : RUN curl -s https://ifconfig.me || true. Si l'IP est la vôtre, le build n'est pas proxifié. Supprimez cette ligne avant de livrer.
• Conteneur : docker exec -it <container> sh -c 'curl -s https://ifconfig.me' et comparez avec votre IP réelle.
• DNS : les proxies HTTP résolvent généralement le DNS du côté du proxy pour HTTPS (via CONNECT), mais les requêtes HTTP simples peuvent fuiter le DNS si le client résout localement. SOCKS5 avec socks5h résout toujours à distance. Si le DNS est important, testez avec un vérificateur de fuite DNS ou inspectez les journaux du proxy.

Pièges courants avec Docker et les proxies

• NO_PROXY n'est pas automatique. Si votre registre interne ou un service sur l'hôte est proxifié inutilement, ajoutez-le à NO_PROXY. Incluez localhost, 127.0.0.1 et tout domaine interne.
• Majuscules vs minuscules. Certains outils lisent HTTP_PROXY, d'autres http_proxy. Définissez les deux en cas de doute. Dans les Dockerfiles, ARG HTTP_PROXY suffit pour que le processus de build lise la variante en majuscules ; ajoutez ARG http_proxy si un outil spécifique a besoin de minuscules.
• Identifiants dans l'historique de build. Les valeurs de --build-arg peuvent apparaître dans docker history. Utilisez les montages secrets de BuildKit (--mount=type=secret) pour les jetons et mots de passe.
• Docker Desktop vs démon Linux. Sur Linux, vous modifiez systemd ; sur Docker Desktop, vous utilisez l'interface graphique ou settings.json. Ne supposez pas qu'un tutoriel Linux s'applique à Docker Desktop.
• IPv6 et double pile. Si votre proxy ne prend en charge qu'IPv4, forcez le conteneur ou le démon à préférer IPv4. Certains outils ont besoin d'un indicateur explicite.

Un workflow pratique pour les réseaux restreints ou filtrés

Si vous travaillez depuis un réseau où l'accès au registre est lent, limité ou filtré — courant dans certains réseaux d'entreprise et nationaux — commencez par le proxy du démon pour que les pulls d'images réussissent. Ajoutez ensuite les arguments de build pour les gestionnaires de paquets. Enfin, définissez les variables d'environnement d'exécution uniquement pour les conteneurs qui ont besoin de sortir via le proxy. Si votre seul point de terminaison proxy est SOCKS5, exécutez un pont local et pointez les variables de proxy HTTP de Docker vers celui-ci, ou gardez SOCKS5 à l'intérieur du conteneur pour les applications qui le prennent en charge directement.

Cette approche en couches évite d'envoyer tout le trafic des conteneurs via le proxy alors que seuls les pulls d'images et les étapes de build le nécessitent. Cela permet également de garder les identifiants dans moins d'endroits.

À retenir

La configuration du proxy Docker n'est pas un seul paramètre ; c'est un paramètre de démon, un argument de build et une variable d'environnement par conteneur. SOCKS5 n'est pris en charge que là où l'application le prend en charge — le démon Docker ne le fait pas. En configurant chaque couche délibérément et en vérifiant avec docker info, un pull de test et une vérification d'IP dans le conteneur, vous pouvez maintenir le fonctionnement des builds sans fuite de DNS ni intégration d'identifiants dans les images.