tl;dr: Batect will do its best to make things just work with proxies, but you'll need to configure proxies for pulling images yourself
Most applications expect to find proxy configuration in a number of environment variables. The most common are:
http_proxy: proxy to use for HTTP requests
https_proxy: proxy to use for HTTPS requests
ftp_proxy: proxy to use for FTP requests
no_proxy: comma-separated list of domains or addresses for which connections should bypass the proxy (ie. be direct to the destination)
There are three points where a proxy could be required during the lifecycle of a container:
- while the image is being pulled
- while build steps are running, after the image has been pulled
- while the container is running
Each of these are handled slightly differently by Docker, and so Batect does its best to make your life easier.
When pulling an image, the Docker daemon uses either proxy-related environment variables from the daemon's environment or settings from its configuration file. These settings cannot be set at image pull time, so Batect can't configure these settings for you - you must configure them yourself:
On macOS, Docker defaults to using your system's proxy settings, and you can change these by going to the Docker icon > Preferences > Proxies.
On Linux, you may need to configure the Docker daemon's proxy settings yourself. This page in the Docker documentation gives an example of how to configure a Docker daemon running with systemd.
On Windows, you may need to configure the Docker daemon's proxy settings yourself. You can edit Docker's proxy settings by right-clicking the Docker taskbar icon, choosing Settings and then Proxies.
After pulling the base image, all subsequent build steps use the environment variables of the build environment, which is a combination of:
- any environment variables defined in the base image with
- any build arguments defined in the Dockerfile with
- any environment variables defined in the Dockerfile with
- any of the pre-defined build arguments, if a value is provided for them
This last point is the most relevant to proxy settings - as
no_proxy etc. are defined as
pre-defined build arguments, we can pass the host's proxy environment variables into the build environment as build arguments.
Batect automatically propagates any proxy environment variables configured on the host as build arguments unless the
flag is passed to
Note that build arguments are not persisted in the image - they exist only as environment variables at build time. Furthermore,
the pre-defined proxy-related build arguments (unlike normal build arguments) do not impact Docker's cache invalidation logic -
so if an image build succeeded with
http_proxy set to
not cause a rebuild. (The reasoning behind this is that if the build has succeeded with one proxy, then switching to another
proxy should have no impact.)
The set of run time environment variables is defined by:
- any environment variables defined in the image (including any base images) with
- any container-specific environment variables specified in the container or task in
Batect automatically propagates any proxy environment variables configured on the host as environment variables unless the
--no-proxy-vars flag is passed to
If propagating proxy environment variables is enabled, and any proxy environment variable recognised by Batect
is set, Batect will also add the names of all containers started as part of the task to
NO_PROXY (or create those environment variables if they're not set).
This ensures that inter-container communication is not proxied.
Batect will propagate the following proxy-related environment variables:
Batect will add missing environment variables if only one in a pair is defined. For example, if
HTTP_PROXY isn't, then both
HTTP_PROXY are propagated, with
HTTP_PROXY set to the same value as
If you run a local proxy on your host machine such as Cntlm, referring to this proxy with
will not work from inside a Docker container. Within a container,
localhost refers to the container, not the host machine.
If you are running Batect on macOS or Windows with Docker 17.06 or later, Batect will automatically rewrite proxy-related environment
variables that refer to
::1 so that they refer to the host machine.
If you are running Batect on Linux, or using an older version of Docker, Batect will not rewrite proxy-related environment variables. Support for Linux will be added in the future, check this issue on GitHub for updates.