Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Proxies

When http_proxy, https_proxy, ftp_proxy or no_proxy are set in the environment Ratect itself runs in — in either case, so HTTP_PROXY too — they are injected into every container’s environment and every image build’s build arguments. A task or a build that needs to reach the network through a proxy just works, without repeating the proxy settings in environment or build_args by hand. There is no config field for this in either format; it is automatic, on both binaries, and --no-proxy-vars turns it off. This page is the one description of what is injected, how it is adjusted for a container’s point of view, and what it can’t fix.

Precedence

Where an injected variable sits among a container’s other environment variables, and among a build’s build_args — what overrides it on a key collision — is Environment precedence.

Proxies from Docker’s config.json

An image build also gets the proxies set in the proxies section of the Docker CLI’s config.json, as docker build and Batect builds do. It is the same file Ratect reads registry credentials and contexts from: in the directory --docker-config names, else DOCKER_CONFIG, else ~/.docker.

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

The entry used is the one keyed by the Docker host the run connects to, spelled as the Docker CLI spells it (unix:///var/run/docker.sock, tcp://build-host:2376), else default. Each of its httpProxy, httpsProxy, ftpProxy, noProxy and allProxy becomes a build argument in both cases — HTTP_PROXY and http_proxy, and so on — but only where the build doesn’t already have that argument, so a proxy from the environment and a container’s own build_args both win over it. The values are passed as written: none of the adjustments below are made to them.

This is for image builds only; a container’s environment gets nothing from config.json. A missing config.json, or one with no proxies, adds nothing.

no_proxy is extended

Every container sharing a task’s network — the task’s own container and each of its dependencies — has its own name appended to no_proxy/NO_PROXY, so traffic between them isn’t sent through the proxy. Not done for image builds: nothing is running yet during a build, so there is nothing to exempt.

A proxy on localhost

An http_proxy/https_proxy/ftp_proxy value that points at localhost, 127.0.0.1 or ::1 is rewritten to host.docker.internal, since localhost from inside a container refers to the container itself, not the machine running the proxy. A value that isn’t an http/https URL, or doesn’t refer to the local machine, is left unchanged.

This happens on every platform, including Linux — where, unlike under Docker Desktop, nothing supplies host.docker.internal by itself. So a run that rewrote a URL also adds host.docker.internal:host-gateway to every container it starts and every image it builds, using Docker’s own --add-host mechanism, which the daemon resolves to the machine running it. That entry is added on every platform too, not only the one that needs it: on macOS and Windows it names the same gateway Desktop would have answered with, so it is a new /etc/hosts line rather than a change in what the container can reach. What gates it is the rewrite, not the platform — no rewrite, no entry — and a container’s own additional_hosts entry for that name always wins over it.

A proxy bound to loopback only

Rewriting the URL can’t make an unreachable proxy reachable. A proxy bound only to 127.0.0.1 — which is what cntlm and similar default to — still refuses a connection from a container, so on Linux Ratect checks /proc/net/tcp/tcp6 and warns, once per run and naming the port:

The proxy on port 3333 is listening on loopback addresses only, so containers in this run cannot reach it even though its URL now names the host. Bind the proxy to 0.0.0.0 to make it reachable — which also exposes it to anything else that can reach this machine, so do that only on a network you trust. Use --no-proxy-vars if this run doesn’t need the proxy.

It’s a warning, not a failure: the run may never use the proxy. Note the security cost it names — binding a proxy to 0.0.0.0 opens it to everything that can reach the machine, so weigh that rather than applying it reflexively. Some proxies offer the same thing as a narrower setting: cntlm, for instance, binds 127.0.0.1:3128 by default and listens on every interface only under its Gateway option.

A host firewall

A host firewall can block the container’s traffic even when the proxy is bound wide enough, and that case Ratect can’t detect — so if the warning doesn’t fire and the proxy still isn’t reachable, check there next.

What to look for: the connection arrives on the bridge interface of the user-defined network the run is using, never Docker’s default docker0 bridge, so a firewall rule written for docker0 won’t cover it. Ratect creates a network per task, or uses the one --use-network names — and a run can’t fall back to the default bridge even if you point --use-network at it, because Ratect gives every container on it a network-scoped alias and Docker only allows those on user-defined networks (docker run refuses with network-scoped aliases are only supported for user-defined networks).

Match the rule on that network’s subnet, which docker network inspect <network> reports under IPAM.Config. Its interface name is generally not in that output — Docker only records one there when the network was created with com.docker.network.bridge.name, which is how docker0 itself gets its name — so a rule pinned to an interface is both harder to write and easier to get wrong.

Turning it off

--no-proxy-vars disables all of the above for one run: nothing is injected into any container or build — the proxies from Docker’s config.json included — no_proxy is left alone, and no URL is rewritten. A container’s own build_args are still passed. It is a ratect run option, and a ratect-compat flag.

Coming from Batect? Three deliberate differences: a localhost proxy is rewritten on Linux too, where Batect propagates it verbatim; a loopback-bound proxy is diagnosed rather than left to fail; and --no-proxy-vars keeps the proxies from Docker’s config.json out of a build, where Batect passes them whatever its flag says. All three are listed under Differences from Batect.