Skip to main content

Set Up Proxy for Docker Registry

Configure the proxy where registry requests originate. Docker daemon settings cover pulling job containers; Build Image uses a separate BuildKit builder, and Build Image (Kaniko), Pull Image, and Push Image contact registries from their step containers.

Docker Daemon​

Follow Docker's daemon proxy guide on each machine that executes Docker jobs. For example, set these variables in the daemon's startup environment:

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

Restart the daemon after changing its configuration. Docker Desktop uses its own proxy settings; daemon.json proxy settings are ignored there. Setting variables only in your terminal or build step does not configure an already-running daemon.

Include the proxy URL scheme even when the registry uses HTTPS. Add internal registries to NO_PROXY when they should be contacted directly.

Build Image​

Create a dedicated BuildKit builder with proxy variables on each eligible executor host:

docker buildx create --name onedev-proxy --driver docker-container \
  --driver-opt env.http_proxy=http://proxy.example.com:3128 \
  --driver-opt env.https_proxy=http://proxy.example.com:3128 \
  --driver-opt env.no_proxy=registry.internal.example.com

In Administration → Job Executors → More Settings, set Buildx Builder to onedev-proxy. Run the command as the user and against the Docker daemon used by the executor. For containerized servers or agents, also make the builder configuration available inside the container as described in Configure Docker Builder.

The proxy address must be reachable from the BuildKit container. localhost there identifies the container itself. The example passes a single no_proxy host; if passing multiple hosts, account for Buildx's comma-separated --driver-opt parsing.

Kaniko, Pull Image, and Push Image​

Edit the step and add proxy variables under More Settings → Environment Variables. For example:

envVars:
- name: HTTP_PROXY
  value: http://proxy.example.com:3128
- name: HTTPS_PROXY
  value: http://proxy.example.com:3128
- name: NO_PROXY
  value: localhost,127.0.0.1,registry.internal.example.com

These configure registry requests made by the step process. The Docker daemon still needs its own configuration to download the container image that runs the step.

Verify​

Run a job that builds from or pulls an uncached public image, then check both the job result and your proxy's connection log. A successful job alone does not prove it used the proxy: the image may have been cached or the registry may match NO_PROXY. For an internal registry excluded by NO_PROXY, verify that it remains reachable directly.