env | grep -i proxy

Docker has revolutionized how developers package and deploy software applications by allowing everything an app needs to run to be bundled into portable containers. However, in some restricted networking environments, Docker containers may not have direct access to the internet. In these cases, configuring Docker to use a proxy server allows the containers to connect out to online resources they need.

Content Navigation show

By default, Docker does not use a proxy server. Additional configuration is required to enable Docker containers to access the internet through a proxy. There are a few different methods to set this up depending on your environment and requirements. In this guide, we‘ll walk through three ways to configure Docker to use a proxy:

  1. Manual configuration in Docker Desktop
  2. Editing the Docker daemon configuration file
  3. Setting environment variables

We‘ll cover what you need to get started, the detailed steps for each method, some best practices to keep in mind, and the benefits and limitations of using a proxy with Docker. By the end, you‘ll be equipped to configure Docker to work in restricted network environments and access the internet resources your containerized applications require. Let‘s dive in!

Prerequisites

Before configuring Docker to use a proxy, you‘ll need to have a couple key components in place:

Docker Desktop: The Docker Desktop application needs to be installed on your development machine. It‘s available for Windows, macOS and Linux. You can download the appropriate version for your operating system from the official Docker website.

Proxy Server: You‘ll need access to a proxy server that Docker will use to connect to the internet. This could be a dedicated proxy appliance or a server configured to proxy requests. You‘ll need to know the hostname or IP address and port of the proxy server. If the proxy requires authentication, you‘ll also need valid credentials.

Method 1: Configure Docker Desktop

The Docker Desktop application provides a user-friendly GUI to configure many Docker settings, including proxy setup. This is a good place to start if you are less comfortable editing configuration files directly.

Here are the steps to set the proxy in Docker Desktop:

  1. Open the Docker Desktop application. You should see the Docker menu bar icon indicating Docker is running.
  2. Click on the Docker menu bar icon and select "Preferences" (or "Settings" on Windows).
  3. In the Preferences window, click on the "Resources" tab on the left, then select "Proxies".
  4. Click to toggle on the "Manual proxy configuration" option.
  5. Enter the proxy server details in the appropriate fields:
    • Web Server (HTTP): Enter the hostname or IP and port for an HTTP proxy
    • Secure Web Server (HTTPS): Enter the hostname or IP and port for an HTTPS proxy
    • Bypass for these hosts & domains: Enter any hosts or domains the proxy should not be used for, separated by commas
  6. Click "Apply & Restart" to save the settings and restart Docker Desktop

With these settings, Docker will send web requests through the configured HTTP or HTTPS proxy server when pulling images from Docker Hub or other registries. However, this only sets the proxy for Docker Desktop itself to pull images – it does not configure the proxy inside a container. We‘ll look at how to do that next.

Method 2: Edit the Docker Daemon Configuration File

To configure proxy settings that will apply within running containers, we need to modify the Docker daemon configuration file. The daemon uses this file to set system-wide configuration when it starts up.

Follow these steps to edit the Docker daemon config:

  1. Check if the Docker daemon configuration file already exists with:

    $ sudo cat /etc/docker/daemon.json

    If the file doesn‘t exist, that‘s ok, we‘ll create it in the next step. If it does exist, you‘ll see the current configuration. We‘ll be adding the proxy settings to this.

  2. Open or create the daemon.json file for editing:

    $ sudo nano /etc/docker/daemon.json

  3. Add the following proxy configuration to the file:

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

    Replace the httpProxy and httpsProxy values with your HTTP and HTTPS proxy server hostnames or IPs and ports. The noProxy setting lists hosts or addresses that should bypass the proxy.

  4. Save the file and exit the editor.
  5. Restart the Docker daemon to pick up the configuration changes:

    $ sudo systemctl restart docker

With the daemon restarted, new containers will launch with these proxy settings in place. Verify the settings took effect by launching a new container and checking its environment:


$ docker run -it --rm alpine sh

HTTP_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://proxy.example.com:3128
NO_PROXY=localhost,127.0.0.1

Method 3: Set Docker Environment Variables

A third option to configure the proxy is to set Docker-specific environment variables on the host. When the Docker daemon starts up, it will use these environment variables to set the proxy configuration.

Follow these steps to set the Docker proxy environment variables:

  1. Edit the Docker systemd service file. This is normally located at /lib/systemd/system/docker.service:

    $ sudo nano /lib/systemd/system/docker.service

  2. Modify the [Service] section to add the proxy environment variables:


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

    Substitute your proxy server details. Save the file when done.

  3. Reload the systemd configuration:

    $ sudo systemctl daemon-reload

  4. Restart Docker:

    $ sudo systemctl restart docker

  5. Verify the environment variables are set for the Docker process:


    $ systemctl show --property=Environment docker
    Environment=HTTP_PROXY=http://proxy.example.com:3128 HTTPS_PROXY=http://proxy.example.com:3128 NO_PROXY=localhost,127.0.0.1

Now when you launch new containers, they will inherit these proxy settings from the Docker daemon‘s environment.

Best Practices for Configuring a Docker Proxy

Whichever method you use to configure the Docker proxy, here are some tips to ensure it works smoothly:

  • Match proxy settings exactly – Verify the proxy hostname/IP and port are identical between your Docker configuration and the actual proxy setup. Even small typos can cause the proxy connection to fail.
  • Test, test, test! – After setting the proxy configuration, always test it with simple containers to pull images and access the internet before deploying your application. Watch the Docker logs for any error messages related to the proxy.
  • Consider the scope – Think carefully about where you set the proxy and the scope of the configuration. Setting specific proxy settings for a single container is more secure than broad environment variables that apply to every container.
  • Secure your credentials – If your proxy requires authentication, be very careful with how you handle the credentials. Avoid saving passwords in plaintext. Consider using Docker or OS native secret management where possible.

Benefits of Using a Proxy Server with Docker

Configuring Docker to use a proxy server unlocks several key benefits:

  • Access to internet resources – In restricted or airgapped networks, a proxy allows Docker to pull images and containers to access online APIs, databases, or other resources they need.
  • Improved security – Proxies add an additional layer of network security by controlling and monitoring traffic flow. SSL decryption, content filtering, and malware scanning are often performed on proxied connections.
  • Caching for performance – Advanced proxy servers may cache frequently accessed Docker image layers and other content. This can significantly speed up container deployments and reduce bandwidth usage.
  • Simplified network topology – Using a proxy avoids the need to provision internet access to every Docker host. Only the proxy server needs direct external connectivity. Internal subnets can be isolated.

Limitations of Docker Proxy Configuration

As useful as proxies are, there are a couple limitations to be aware of:

  • Proxy server required – To configure Docker with a proxy, you must have a working proxy server already setup and accessible on the network. The proxy needs sufficient resources to handle the Docker traffic load.
  • Incompatible with some setups – Some Docker networking setups, such as using the host network mode, may be incompatible with using a proxy. Not all applications honor proxy settings consistently.
  • Added complexity – Configuring proxies adds an extra layer of complexity to the Docker environment. Troubleshooting connection issues can be more difficult due to the proxy involvement. Specific proxy settings may need to be tested and set per application.

Conclusion

In this guide we covered three methods to configure Docker to use a proxy server:

  1. Setting the proxy in Docker Desktop
  2. Editing the Docker daemon configuration file
  3. Setting Docker environment variables

We also discussed some best practices, benefits, and limitations of combining Docker with a proxy.

Using a proxy server is a common solution to allow Docker containers to access internet resources when running in restricted networking environments. While it adds some extra complexity, a properly configured proxy unlocks the full power of Docker without compromising on security.

The specific proxy setup you use will depend on the needs of your application, Docker environment, and network architecture. But with these configuration options, you have the flexibility to adapt Docker to work optimally behind a proxy. Happy Dockering!

Tags: