Master Docker Proxy Configuration: From daemon to containers and builds

Sometimes network conditions such as corporate NAT require the use of a proxy. Docker proxy configuration can be complex because there are three scenarios, but the underlying principle is the same: using Linux environment variables like http_proxy.

dockerd Proxy

When executing docker pull, the daemon dockerd performs the operation, so the proxy must be configured in the daemon’s environment. This environment is managed by systemd, so the proxy settings belong in the systemd service configuration.

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

In the proxy.conf file (any *.conf name works), add the following content:

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

Replace proxy.example.com:8080 with a reachable, password‑less proxy. Tools like cntlm can be used to set up a local proxy that forwards to the corporate proxy.

Container Proxy

During container runtime, proxy settings can be placed in ~/.docker/config.json. The following configuration is effective for Docker 17.07 and later:

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

This user‑level configuration also stores other information such as docker login credentials and can include formatting or plugin parameters. Alternatively, proxy variables can be injected at container start with the -e flag, which is preferable in CI/CD pipelines or production environments to avoid hard‑coding proxy settings.

docker build Proxy

Although docker build runs inside a temporary container, it does not inherit the user‑level config.json. Therefore, proxy variables must be passed as build arguments:

docker build . \
    --build-arg "HTTP_PROXY=http://proxy.example.com:8080/" \
    --build-arg "HTTPS_PROXY=http://proxy.example.com:8080/" \
    --build-arg "NO_PROXY=localhost,127.0.0.1,.example.com" \
    -t your/image:tag

Note that both docker run and docker build operate in isolated networks by default. If the proxy is bound to localhost:3128, it will not be reachable unless the container is started with --network host. In most cases, use an external proxy IP and enable gateway mode on the proxy server.