Docker Proxy Setup Guide - Mirror Acceleration and Proxy Configuration in China

Quick Linux Proxy Setup#

If you haven’t set up a proxy on Linux yet, the clash-for-linux-install project provides a quick deployment solution.

Installation command:

1
git clone --branch master --depth 1 https://gh-proxy.org/https://github.com/nelvko/clash-for-linux-install.git && cd clash-for-linux-install && bash install.sh

Common commands:

1
Usage:
2
  clashctl COMMAND [OPTIONS]
3

4
Commands:
5
    on                    Enable proxy
6
    off                   Disable proxy
7
    status                Kernel status
8
    proxy                 System proxy
9
    ui                    Web panel
10
    secret                Web secret key
11
    sub                   Subscription management
12
    upgrade               Upgrade kernel
13
    tun                   Tun mode
14
    mixin                 Mixin configuration
15

16
Global Options:
17
    -h, --help            Show help information

Understanding Proxy Address Selection#

Before configuring Docker proxy, you need to understand where your proxy is deployed:

Scenario 1: Proxy on a Remote Server (accessed via Tailscale/WireGuard)

1
┌─────────────────┐      VPN Network      ┌─────────────────┐
2
│  Proxy Server   │◄────────────────────►│  Local (Docker)  │
3
│  100.98.32.42   │                       │                  │
4
│  :7890          │                       │                  │
5
└─────────────────┘                       └──────────────────┘

In this case, both the host and containers can directly use the remote proxy address 100.98.32.42:7890. Docker containers (even with bridge network) route traffic through the host, which can access the VPN network normally.

Scenario 2: Proxy Running on the Host Locally

1
┌─────────────────────────────────────────┐
2
│  Host Machine                            │
3
│  ┌─────────────┐    ┌─────────────────┐ │
4
│  │ Proxy       │    │ Docker Container│ │
5
│  │ 127.0.0.1   │◄───│ (bridge network)│ │
6
│  │ :7890       │    │                 │ │
7
│  └─────────────┘    └─────────────────┘ │
8
└─────────────────────────────────────────┘

This scenario is more complex:

• Services on the host can directly use 127.0.0.1:7890
• But 127.0.0.1 inside a container refers to the container itself, not the host
• Containers need to use 172.17.0.1:7890 (docker0 bridge address) to access the proxy on the host

Docker Pull/Push Proxy Configuration#

Docker’s pull and push commands are managed by systemd, so you need to configure proxy environment variables for the Docker service.

Create the configuration directory and file:

1
sudo mkdir -p /etc/systemd/system/docker.service.d
2
sudo vim /etc/systemd/system/docker.service.d/http-proxy.conf

Add the following content (replace with your own proxy address):

1
[Service]
2
Environment="HTTP_PROXY=http://100.98.32.42:7890"
3
Environment="HTTPS_PROXY=http://100.98.32.42:7890"

NOTE

If the proxy is running locally on the host, you can use 127.0.0.1:7890 here since the Docker daemon runs on the host.

Reload the configuration and restart Docker:

1
sudo systemctl daemon-reload
2
sudo systemctl restart docker

Verify the configuration:

1
sudo systemctl show --property=Environment docker

Now docker pull will use the proxy to fetch images.

Using Proxy During Docker Build#

When building images, pass proxy settings via the --build-arg parameter:

1
docker build \
2
    --build-arg http_proxy=http://100.98.32.42:7890 \
3
    --build-arg https_proxy=http://100.98.32.42:7890 \
4
    -t image_name .

NOTE

If your proxy is on a remote server (accessed via VPN), use the remote address directly. Container network traffic routes through the host, which can access proxies in the VPN network normally.

If the proxy is running locally on the host, use the docker0 bridge address:

1
docker build \
2
    --build-arg http_proxy=http://172.17.0.1:7890 \
3
    --build-arg https_proxy=http://172.17.0.1:7890 \
4
    -t image_name .

Or use --network=host to let the build process use the host network directly:

1
docker build --network=host \
2
    --build-arg http_proxy=http://127.0.0.1:7890 \
3
    --build-arg https_proxy=http://127.0.0.1:7890 \
4
    -t image_name .

Docker Global Proxy Configuration#

Configure ~/.docker/config.json to set proxy for all newly created containers:

1
vim ~/.docker/config.json

1
{
2
    "proxies": {
3
        "default": {
4
            "httpProxy": "http://100.98.32.42:7890",
5
            "httpsProxy": "http://100.98.32.42:7890",
6
            "noProxy": "localhost,127.0.0.1,.local"
7
        }
8
    }
9
}

IMPORTANT

This configuration only affects containers created by build and run. It does not affect docker pull. For pull, you still need to configure the systemd proxy as described above.

CAUTION

Once a container is created, proxy environment variables are embedded in it. Even if you modify or delete config.json later, existing containers will still use the proxy settings from creation time. To disable proxy, manually clear environment variables inside the container:

1
export http_proxy=
2
export https_proxy=

Using Proxy Inside Containers#

Sometimes you need to access external networks from within a running container. Here are several common methods.

1
export ALL_PROXY='socks5://100.98.32.42:7890'
2
# or
3
export http_proxy='http://100.98.32.42:7890'
4
export https_proxy='http://100.98.32.42:7890'

1
export ALL_PROXY='socks5://172.17.0.1:7890'

1
docker run --network=host your_image

1
export ALL_PROXY='socks5://127.0.0.1:7890'

Verify Container Can Access Proxy#

Test proxy connectivity from inside a container:

1
# Test HTTP proxy
2
curl -x http://100.98.32.42:7890 https://www.google.com
3

4
# Test SOCKS5 proxy
5
curl -x socks5://100.98.32.42:7890 https://www.google.com

Check docker0 Bridge Address#

1
ip addr show docker0

Usually it’s 172.17.0.1, but it may vary depending on configuration.

Confirm VPN Network is Reachable#

If the proxy is accessed via VPN, first confirm connectivity from the host:

1
curl -x http://100.98.32.42:7890 https://www.google.com

SOCKS5 Proxy Support#

Docker’s config.json currently only supports HTTP/HTTPS/FTP protocols, not SOCKS5 directly. If you’re using Clash or similar proxies with mixed port support, the same port typically supports both HTTP and SOCKS5. Just use HTTP configuration.

Temporarily Disabling Proxy#

If you have global proxy configured but need to temporarily disable it:

1. Rename the ~/.docker/config.json file
2. Clear environment variables inside container: export http_proxy= https_proxy=
3. Override with --build-arg http_proxy= --build-arg https_proxy=