I think it is supposed to be http here, quoting @djs55:

Confusingly a HTTPS proxy is a HTTP server which accepts CONNECT host:port HTTP requests and establishes a tunnel, which the client then sends TLS back and forth but the proxy doesn't understand (in some ways this is easier than in the HTTP case where the proxy has a bunch of rules about what to do with headers)

I think both should work, although it could depend on the implementation.

It's really a "fuzzy" area, without any (good) standards. e.g. Golang also made a silly (and breaking) change and started to ignore HTTP_PROXY for https connections; https://docs.docker.com/engine/release-notes/#201010

I think

• the httpProxy (HTTP_PROXY) will be used to proxy http:// connections
• the httpsProxy (HTTPS_PROXY) will be used to proxy https:// connections

where the connection to the proxy can either be plaintext http://proxy:3128 or itself using TLS https://proxy:3128. So there can be 0, 1 or 2 layers of TLS.

If the underlying connection is TLS, then the only reason to use TLS to talk to the proxy too is to protect the authorization header which could include a base64-encoded password. The destination server is sent in the clear even with TLS (as a Server Name Indication) so the HTTP CONNECT <server:443> part is not secret.

So I think the examples are ok. My main problem with the docs as they are is that there are a confusing number of places where proxies can be configured. I think this PR makes an improvement though!

Ah that one had https though… 🤔

It might be worth also showing an example somewhere where;

• the proxy is set manually during build (--build-arg)
• the proxy is set manually during "run" (--env)

perhaps also an example where the proxy is taken from the current environment (this could be a follow-up). Use-case here would be that the host is configured with a proxy; by default, (build-)containers do not inherit those environment variables (by design), but it may be that you need them to have the same proxy configured.

# proxy configuration on my host
env | grep _PROXY
HTTPS_PROXY=https://my-hosts-proxy.example
HTTP_PROXY=http://my-hosts-proxy.example

# run a container that inherits the values from those by setting the name of the env-var, but no value (no `=`);
docker run -e HTTPS_PROXY -e HTTP_PROXY --rm alpine sh -c 'env | grep _PROXY'
HTTPS_PROXY=https://my-hosts-proxy.example
HTTP_PROXY=http://my-hosts-proxy.example

docker build --no-cache --progress=plain --build-arg HTTPS_PROXY --build-arg HTTP_PROXY -<<'EOF'
FROM alpine
RUN env | grep -i _PROXY
EOF

#5 [2/2] RUN env | grep -i _PROXY
#0 0.106 HTTPS_PROXY=https://my-proxy.example
#0 0.106 https_proxy=https://my-proxy.example
#0 0.106 http_proxy=http://my-proxy.example
#0 0.106 HTTP_PROXY=http://my-proxy.example
#5 DONE 0.1s

I think this one needs to be tcp://docker-daemon1.example.com (but would have to verify that).

Do you think (for a follow-up?) it would be useful to show an example as well where both "default" and "other is configured?

cat ~/.docker/config.json
{
	"proxies": {
		"default": {
			"httpProxy": "http://192.168.1.12:1111"
		},
		"unix:///Users/thajeztah/.docker/run/docker.sock": {
			"httpProxy": "http://192.168.1.12:2222"
		}
	}
}

And we could show examples, including how it interacts with docker context;

docker context ls
NAME                TYPE                DESCRIPTION                               DOCKER ENDPOINT                                   KUBERNETES ENDPOINT   ORCHESTRATOR
default *           moby                Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux       moby                                                          unix:///Users/thajeztah/.docker/run/docker.sock


# uses "default" (if set)
docker run --rm  alpine sh -c 'env | grep _PROXY'
HTTP_PROXY=http://192.168.1.12:1111

# uses proxy for "unix:///Users/thajeztah/.docker/run/docker.sock"
docker --host unix:///Users/thajeztah/.docker/run/docker.sock run --rm  alpine sh -c 'env | grep _PROXY'
HTTP_PROXY=http://192.168.1.12:2222

# also uses proxy for "unix:///Users/thajeztah/.docker/run/docker.sock"
docker --context=desktop-linux run --rm  alpine sh -c 'env | grep _PROXY'
HTTP_PROXY=http://192.168.1.12:2222

(and, yes, we should integrate that with docker context itself, and have it be part of the context's options)

☝️ I should mention that it looks like there's currently a bug in the CLI, and setting a "per-host" proxy for a ssh:// connection doesn't work (it tries to look up using our "magic" http://docker.example.com hostname, which is used internally.

That's a cool example. Let's add it in a follow-up - for now I can try to clarify the confusion with the key names, and maybe add both a default and a "named" daemon.

TBH, I find contexts a confusing topic overall. Maybe that's an area worth spending some time trying to clarify.