fix(docker): address review feedback for #605

- Extract resolveDockerHost() helper so the config -> env -> default
  precedence is documented and independently testable, instead of
  inlined inside createHTTPClient.
- Add TestResolveDockerHost to pin the precedence contract.
- Extend TestCreateHTTPClient_DockerHostEnvVar with an HTTPS case that
  also asserts ForceAttemptHTTP2 is opt-in for https:// hosts.
- Add a CHANGELOG entry under [Unreleased].
- Document the failure mode and the recommended docker-socket-proxy
  configuration in docs/TROUBLESHOOTING.md.

Refs #605, #606.

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>

Author: CybotTM

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- `DOCKER_HOST` is now honored when selecting the HTTP transport dialer. Previously, with `DOCKER_HOST=tcp://...` (e.g. a Docker socket proxy) the client silently dialed `unix:///var/run/docker.sock` and startup failed with a misleading "Cannot connect to the Docker daemon at tcp://…" error ([#606](https://github.com/netresearch/ofelia/pull/606), fixes [#605](https://github.com/netresearch/ofelia/issues/605))
+
 ## [0.24.0] - 2026-05-10
 
 ### Changed

core/adapters/docker/client.go

@@ -124,23 +124,28 @@ func newClientFromSDK(sdk *client.Client) *Client {
 	return c
 }
 
+// resolveDockerHost mirrors the SDK's client.FromEnv host resolution so the
+// custom HTTP transport's dialer ends up targeting the same endpoint as the
+// SDK. Precedence: explicit config > DOCKER_HOST > client.DefaultDockerHost.
+// Without this, an empty config.Host plus DOCKER_HOST=tcp://... silently
+// routes every request through a unix socket dialer pinned to
+// /var/run/docker.sock. See issue #605.
+func resolveDockerHost(configHost string) string {
+	if configHost != "" {
+		return configHost
+	}
+	if envHost := os.Getenv("DOCKER_HOST"); envHost != "" {
+		return envHost
+	}
+	return client.DefaultDockerHost
+}
+
 // createHTTPClient creates an HTTP client with connection pooling.
 func createHTTPClient(config *ClientConfig) *http.Client {
 	// Determine if we should use HTTP/2
 	// Docker daemon only supports HTTP/2 over TLS (ALPN negotiation)
 	// For Unix sockets and plain TCP, we use HTTP/1.1
-	//
-	// Host resolution must mirror what the SDK's client.FromEnv option does
-	// (read DOCKER_HOST when not set explicitly); otherwise the dialer here
-	// can fall back to a unix socket while the SDK is trying to reach a TCP
-	// endpoint such as a Docker socket proxy. See issue #605.
-	host := config.Host
-	if host == "" {
-		host = os.Getenv("DOCKER_HOST")
-	}
-	if host == "" {
-		host = client.DefaultDockerHost
-	}
+	host := resolveDockerHost(config.Host)
 
 	transport := &http.Transport{
 		MaxIdleConns:          config.MaxIdleConns,

core/adapters/docker/client_mutation_test.go

@@ -158,33 +158,50 @@ func TestCreateHTTPClient_HostConditions(t *testing.T) {
 // Previously the dialer always fell back to a Unix socket, breaking TCP setups
 // (e.g. Docker socket proxy) even though the SDK itself read DOCKER_HOST via
 // client.FromEnv.
+//
+// Invariant under test: only the unix:// branch of createHTTPClient installs
+// a transport.DialContext closure. For TCP/HTTPS we rely on net.Dial via the
+// standard transport, so DialContext==nil is the signal that "this transport
+// will route to the URL's host" rather than to a hard-coded unix socket.
 func TestCreateHTTPClient_DockerHostEnvVar(t *testing.T) {
 	testCases := []struct {
 		name           string
 		configHost     string
 		envHost        string
 		wantUnixDialer bool
+		wantForceHTTP2 bool
 		desc           string
 	}{
 		{
 			name:           "tcp_via_env_with_empty_config",
 			configHost:     "",
 			envHost:        "tcp://docker-proxy:2375",
 			wantUnixDialer: false,
+			wantForceHTTP2: false,
 			desc:           "DOCKER_HOST=tcp://... must produce a TCP-capable transport (no unix dialer)",
 		},
 		{
 			name:           "unix_via_env_with_empty_config",
 			configHost:     "",
 			envHost:        "unix:///custom/docker.sock",
 			wantUnixDialer: true,
+			wantForceHTTP2: false,
 			desc:           "DOCKER_HOST=unix://... must produce a unix dialer",
 		},
+		{
+			name:           "https_via_env_with_empty_config",
+			configHost:     "",
+			envHost:        "https://docker.example.com:2376",
+			wantUnixDialer: false,
+			wantForceHTTP2: true,
+			desc:           "DOCKER_HOST=https://... must opt into HTTP/2 and use no unix dialer",
+		},
 		{
 			name:           "config_host_wins_over_env",
 			configHost:     "tcp://from-config:2375",
 			envHost:        "unix:///should-be-ignored.sock",
 			wantUnixDialer: false,
+			wantForceHTTP2: false,
 			desc:           "Explicit config.Host must take precedence over DOCKER_HOST",
 		},
 	}
@@ -214,10 +231,37 @@ func TestCreateHTTPClient_DockerHostEnvVar(t *testing.T) {
 			if !tc.wantUnixDialer && hasDialer {
 				t.Errorf("%s: expected no unix dialer (DialContext nil) but it was set", tc.desc)
 			}
+			if transport.ForceAttemptHTTP2 != tc.wantForceHTTP2 {
+				t.Errorf("%s: ForceAttemptHTTP2 = %v, want %v", tc.desc, transport.ForceAttemptHTTP2, tc.wantForceHTTP2)
+			}
 		})
 	}
 }
 
+// TestResolveDockerHost pins the precedence contract: explicit config wins,
+// otherwise DOCKER_HOST, otherwise the SDK default. This is the contract the
+// createHTTPClient dialer relies on staying aligned with client.FromEnv.
+func TestResolveDockerHost(t *testing.T) {
+	t.Run("config_wins", func(t *testing.T) {
+		t.Setenv("DOCKER_HOST", "unix:///ignored.sock")
+		if got := resolveDockerHost("tcp://explicit:2375"); got != "tcp://explicit:2375" {
+			t.Errorf("got %q, want explicit config value", got)
+		}
+	})
+	t.Run("env_when_config_empty", func(t *testing.T) {
+		t.Setenv("DOCKER_HOST", "tcp://from-env:2375")
+		if got := resolveDockerHost(""); got != "tcp://from-env:2375" {
+			t.Errorf("got %q, want DOCKER_HOST value", got)
+		}
+	})
+	t.Run("default_when_both_empty", func(t *testing.T) {
+		t.Setenv("DOCKER_HOST", "")
+		if got := resolveDockerHost(""); got == "" {
+			t.Error("resolveDockerHost returned empty when no config and no env — expected SDK default")
+		}
+	})
+}
+
 func TestClientConfig_PoolingOptions(t *testing.T) {
 	// Test various connection pooling configurations
 	testCases := []struct {

docs/TROUBLESHOOTING.md

@@ -181,6 +181,65 @@ docker exec ofelia id
 - TCP socket should only bind to localhost, not 0.0.0.0
 - Consider the security implications before disabling userns-remap in production
 
+### DOCKER_HOST with TCP Socket Proxy (v0.12.0 – v0.24.0)
+
+**Symptoms**:
+
+```
+SDK provider failed to connect to Docker: pinging docker: Cannot connect to the Docker daemon at tcp://<host>:2375. Is the docker daemon running?
+```
+
+The error names the configured `DOCKER_HOST`, but the connection never actually reaches it.
+
+**Affected Versions**: v0.12.0 – v0.24.0 (fixed in v0.24.1+).
+
+**Affected Configurations**:
+
+- `DOCKER_HOST=tcp://…` pointing at a Docker socket proxy (e.g. [tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy)).
+- `DOCKER_HOST=tcp://…` pointing at a remote Docker daemon over plain TCP.
+- Not affected: `DOCKER_HOST=unix://…` and the default `unix:///var/run/docker.sock`.
+
+**Root Cause**:
+The custom HTTP transport built inside the Docker SDK adapter chose its dialer from `ClientConfig.Host` only, which was empty in the production path. It therefore fell back to a Unix-socket dialer pinned to `/var/run/docker.sock`, even though the SDK itself correctly read `DOCKER_HOST` and pointed at the TCP endpoint. Every request was silently routed to a non-existent Unix socket, producing the misleading `Cannot connect to the Docker daemon at tcp://…` error.
+
+**Solutions**:
+
+1. **Upgrade to v0.24.1+** (recommended).
+2. **Workaround for older versions**: bind-mount `/var/run/docker.sock` directly into the container instead of using a TCP socket proxy. This loses the proxy's security restrictions.
+
+**Working example after the fix** (Docker Compose with `tecnativa/docker-socket-proxy`):
+
+```yaml
+services:
+  ofelia:
+    image: ghcr.io/netresearch/ofelia:0.24.1
+    environment:
+      DOCKER_HOST: tcp://ofelia-socket-proxy:2375
+    networks: [ofelia-socket-proxy]
+    depends_on:
+      ofelia-socket-proxy:
+        condition: service_healthy
+
+  ofelia-socket-proxy:
+    image: ghcr.io/tecnativa/docker-socket-proxy:v0.4.2
+    networks: [ofelia-socket-proxy]
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    environment:
+      CONTAINERS: 1
+      POST: 1
+      EXEC: 1
+    healthcheck:
+      test: wget -t1 -T4 -qO- http://127.0.0.1:2375/_ping | grep -q "OK" || exit 1
+
+networks:
+  ofelia-socket-proxy:
+```
+
+**References**:
+- Issue: [#605](https://github.com/netresearch/ofelia/issues/605)
+- Fix: [#606](https://github.com/netresearch/ofelia/pull/606)
+
 ### HTTP/2 Protocol Errors (v0.11.0 Only)
 
 **Symptoms**: