Ultimate Guide to Docker HTTP Proxy Configuration

Using a HTTP proxy is a boon to performance, especially if you have a slow link to the Internet. However if you’re using Docker in a corporate environment, sometimes you are forced to use a HTTP proxy as outgoing connections to ports 80 and 443 are often blocked.

For most applications it’s usually a simple matter of setting an environment variable or changing a config file to configure a HTTP proxy for an application. Docker, though is a little bit tricky to get working as there are no less than four different places where a proxy needs to be configured for it to work correctly.

There are four different places where a HTTP proxy can be used in Docker.

1. Between the Docker client and Docker daemon
2. Between the Docker daemon and the Internet
3. At container run-time
4. At container build-time

Unfortunately each case needs to be configured differently in Docker.

Let’s look at each case individually.

Proxy between Docker client and Docker daemon

The Docker client is very thin and doesn’t do very much on its own.  It simply calls the Docker daemon to perform tasks by making REST requests.

This usually happens over a UNIX domain socket when your Docker client is on the same machine as your Docker daemon.  If, for example, your Docker daemon is running on an Amazon AWS instance and you need to set the $DOCKER_HOST environment variable, then you might need to configure a proxy for the Docker client.

Figure 1, Docker client communicating with Docker daemon via a proxy.

Luckily this scenario is simple and the Docker client honours the well-known environment variables for setting HTTP proxies as shown below.

$ export http_proxy=http://your.proxy:8080
$ export https_proxy=http://your.proxy:8080
$ export no_proxy=localhost,127.0.0.1
$ docker ps
...

Proxy between Docker daemon and the Internet

A common misconception with the Docker client is that it connects to the registry to download an image when you run “docker pull”. Configuring your environment to use a proxy should be enough to pull an image from behind a firewall, right? Unfortunately this is not true. As mentioned above the Docker client only makes REST requests to the Docker daemon and it does the actual work. In this case it is the Docker daemon configuration that needs to be modified.

Figure 2, Docker daemon communicating with HTTP proxy.

The Docker documentation on how to Control and Configure Docker with systemd tells you how to do this and is reproduced below.  As root, run the following commands.

# mkdir -p /etc/systemd/system/docker.service.d

# cat > /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=http://your.proxy:8080"
Environment="HTTPS_PROXY=http://your.proxy:8080"
Environment="NO_PROXY=127.0.0.1,localhost
EOF

# systemctl daemon-reload
# systemctl restart docker

There are a handful of other locations where proxy configurations can be changed for old versions of Docker. Old distributions of Debian and Ubuntu stored proxy information in /etc/default/docker. Just about every modern Linux distribution now uses systemd to run and configure Docker.

Boot2docker, a lightweight Linux distribution used mostly for running Docker on Mac, stores the information in /var/lib/boot2docker/profile. Boot2docker has been replaced by the official Mac desktop app.

Proxy at Container Build-Time and Container Run-Time

The third and fourth points at which a Docker proxy needs to be configured is at container build and container run time.

Most Docker images perform network activity, such as downloading packages from distribution archives or check out source code from Github. When the container is run it will probably also need to make network connections as part of its normal operation. In both these cases in our corporate environment a HTTP proxy must be configured.

Figure 3, Building or running container communicating with HTTP proxy.

One solution is to set the proxy environment variables in the Dockerfile using the ENV command.

FROM debian:jessie

# Don't do this - very bad style
ENV http_proxy http://your.proxy:8080
ENV https_proxy http://your.proxy:8080

This method works for both the container build and container run cases, but we now have hardcoded the fact that we are using a proxy in the image. Now it is no longer possible for anyone who isn’t behind your corporate proxy to build (or use) your container image if it’s distributed outside of your company. Thus, it’s considered bad style to hardcode variables specific to your environment.

The correct way is to use the –build-arg command-line option to “docker build”. This sets environment variables only when building the container image. For example if I have a Dockerfile in my current directory I can build it from behind a firewall like so:

$ docker build \
    --build-arg http_proxy=http://your.proxy:8080 \
    --build-arg http_proxy=http://your.proxy:8080 \
    -t yourimage  .

Compare this with the –env command-line option to “docker run”which set environment variables when running the container.  When running the container from behind a firewall:

$ docker run \
    --env http_proxy=http://proxy.bigcorp.com:8080 \
    --env http_proxy=http://proxy.bigcorp.com:8080 \
    myimage

By using the –build-arg and –env options in this way the container image can be both built, run and distributed outside of the firewalled environment.

As an interesting historical note, before the –build-arg command-line option was introduced in Docker 0.11, hardcoding the proxy environment variables in the Dockerfile was the only way of building a container behind a firewall.  There was no way to pass environment variables to the Docker build command, as the –env option can only be used when calling “docker run”.

May you never have HTTP proxy issues again!