feat: honor DOCKER_HOST for Docker daemon resolution (#4)

Resolve the Docker endpoint from DOCKER_HOST (with the legacy DOCKER_SOCK
override and an OS default fallback) so Podman, rootless setups, and remote
Docker contexts work without assuming /var/run/docker.sock.

start/az start/gcp start bind-mount the resolved unix socket or pass a remote
tcp:// daemon through via DOCKER_HOST; doctor's docker.socket check reports the
resolved endpoint. Adds DockerHostResolveTest and README documentation.

Closes #3

Author: hectorvent

CHANGELOG.md

@@ -9,6 +9,7 @@ This project uses [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- `floci start` (and `floci az`/`floci gcp start`) now honor the standard `DOCKER_HOST` environment variable, so Podman, rootless setups, and remote Docker contexts work without assuming `/var/run/docker.sock`. `DOCKER_HOST` is resolved into a unix socket, remote TCP daemon, or Windows named pipe — unix sockets are bind-mounted, remote TCP daemons are passed through to the container via `DOCKER_HOST`. Precedence is `DOCKER_HOST` → `DOCKER_SOCK` (legacy override) → OS default. `floci doctor`'s `docker.socket` check reports the resolved endpoint ([#3](https://github.com/floci-io/floci-cli/issues/3))
 - Release ships a `darwin/amd64` (Intel macOS) native binary again — built with an x86_64 GraalVM under Rosetta 2 on the Apple Silicon runner, avoiding the unreliable/queue-bound `macos-13` Intel runner that previously caused the target to be dropped (a past release sat 9.5h on `macos-13` before being cancelled). The Homebrew formula bump again wires the `darwin/amd64` SHA, so `brew install` and the install script resolve a real Intel binary instead of 404ing ([#2](https://github.com/floci-io/floci-cli/issues/2))
 ### Fixed
 

README.md

@@ -209,6 +209,38 @@ floci az start --port 4578           # custom host port
 floci az start --persist ./data      # persist state to a host directory
 ```
 
+#### Docker daemon resolution (Podman, rootless, remote contexts)
+
+The Floci container needs access to a Docker-compatible daemon (for Lambda, EC2,
+EKS, MSK, ECR, CodeBuild, and Kafka/Redpanda support). By default `floci start`
+bind-mounts `/var/run/docker.sock`, but it honors the standard `DOCKER_HOST`
+environment variable, so Podman, rootless setups, and remote Docker contexts work
+without extra flags:
+
+```sh
+# Rootless Podman
+export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
+floci start
+
+# Rootful Podman
+export DOCKER_HOST=unix:///run/podman/podman.sock
+floci start
+
+# Remote daemon over TCP
+export DOCKER_HOST=tcp://10.0.0.5:2375
+floci start
+```
+
+Resolution precedence:
+
+1. **`DOCKER_HOST`** — the standard Docker/Podman variable (`unix://` socket, `tcp://` daemon, or `npipe://` on Windows)
+2. **`DOCKER_SOCK`** — legacy override (a bare socket path)
+3. **OS default** — `/var/run/docker.sock` on Linux/macOS, or the Docker named pipe on Windows
+
+For a `unix://` socket the resolved path is bind-mounted into the container; for a
+remote `tcp://` daemon the `DOCKER_HOST` value is passed through to the container
+instead. Run `floci doctor` to see which endpoint was resolved.
+
 ### `floci stop` / `floci az stop`
 
 ```sh
@@ -387,6 +419,11 @@ services:
       - /var/run/docker.sock:/var/run/docker.sock
 ```
 
+> Using Podman or a non-default daemon? Swap the host side of the socket mount for
+> your daemon's socket (e.g. `/run/user/1000/podman/podman.sock:/var/run/docker.sock`).
+> With the CLI, setting `DOCKER_HOST` is enough — see
+> [Docker daemon resolution](#docker-daemon-resolution-podman-rootless-remote-contexts).
+
 ### Azure CI
 
 ```sh

src/main/java/io/floci/cli/commands/StartCommand.java

@@ -81,7 +81,7 @@ public Integer call() {
         List<String> args = new ArrayList<>();
         args.addAll(List.of("-d", "--name", global.container));
         args.addAll(List.of("-p", port + ":4566"));
-        args.addAll(List.of("-v", "/var/run/docker.sock:/var/run/docker.sock"));
+        args.addAll(DockerClient.dockerSocketRunArgs());
         if (persistDir != null) {
             args.addAll(List.of("-v", persistDir + ":/var/lib/floci"));
         }

src/main/java/io/floci/cli/commands/az/AzStartCommand.java

@@ -76,7 +76,7 @@ public Integer call() {
         List<String> args = new ArrayList<>();
         args.addAll(List.of("-d", "--name", global.container));
         args.addAll(List.of("-p", port + ":4577"));
-        args.addAll(List.of("-v", "/var/run/docker.sock:/var/run/docker.sock"));
+        args.addAll(DockerClient.dockerSocketRunArgs());
         if (persistDir != null) {
             args.addAll(List.of("-v", persistDir + ":/app/data"));
         }

src/main/java/io/floci/cli/commands/gcp/GcpStartCommand.java

@@ -76,7 +76,7 @@ public Integer call() {
         List<String> args = new ArrayList<>();
         args.addAll(List.of("-d", "--name", global.container));
         args.addAll(List.of("-p", port + ":4588"));
-        args.addAll(List.of("-v", "/var/run/docker.sock:/var/run/docker.sock"));
+        args.addAll(DockerClient.dockerSocketRunArgs());
         if (persistDir != null) {
             args.addAll(List.of("-v", persistDir + ":/app/data"));
         }

src/main/java/io/floci/cli/docker/DockerClient.java

@@ -173,9 +173,74 @@ public static boolean isInstalled() {
         }
     }
 
+    /** How the Docker daemon is reached, resolved from the environment. */
+    public enum Kind { UNIX, TCP, NPIPE }
+
+    /**
+     * Parsed Docker daemon endpoint. {@code socketPath} is the local socket/pipe path
+     * for {@link Kind#UNIX}/{@link Kind#NPIPE}, and null for {@link Kind#TCP}.
+     */
+    public record DockerHost(Kind kind, String socketPath, String raw) {}
+
+    private static final String DEFAULT_UNIX_SOCKET = "/var/run/docker.sock";
+    private static final String DEFAULT_WINDOWS_PIPE = "\\\\.\\pipe\\docker_engine";
+
+    /** Resolve the Docker endpoint from the current process environment and OS. */
+    public static DockerHost dockerHost() {
+        return parseDockerHost(
+                System.getenv("DOCKER_HOST"),
+                System.getenv("DOCKER_SOCK"),
+                System.getProperty("os.name", ""));
+    }
+
+    /**
+     * Pure resolver for the Docker endpoint. Precedence: {@code DOCKER_HOST}
+     * (standard) → {@code DOCKER_SOCK} (legacy override) → OS default.
+     */
+    public static DockerHost parseDockerHost(String dockerHostEnv, String dockerSockEnv, String osName) {
+        boolean windows = osName != null && osName.toLowerCase().contains("win");
+
+        if (dockerHostEnv != null && !dockerHostEnv.isBlank()) {
+            String value = dockerHostEnv.trim();
+            if (value.startsWith("unix://")) {
+                return new DockerHost(Kind.UNIX, value.substring("unix://".length()), value);
+            }
+            if (value.startsWith("tcp://") || value.startsWith("http://") || value.startsWith("https://")) {
+                return new DockerHost(Kind.TCP, null, value);
+            }
+            if (value.startsWith("npipe://")) {
+                return new DockerHost(Kind.NPIPE, value.substring("npipe://".length()), value);
+            }
+            // No scheme — treat as a bare socket/pipe path.
+            return new DockerHost(windows ? Kind.NPIPE : Kind.UNIX, value, value);
+        }
+
+        if (dockerSockEnv != null && !dockerSockEnv.isBlank()) {
+            return new DockerHost(Kind.UNIX, dockerSockEnv.trim(), dockerSockEnv.trim());
+        }
+
+        if (windows) {
+            return new DockerHost(Kind.NPIPE, DEFAULT_WINDOWS_PIPE, null);
+        }
+        return new DockerHost(Kind.UNIX, DEFAULT_UNIX_SOCKET, null);
+    }
+
+    /** Back-compat accessor for the resolved local socket/pipe path (null for TCP). */
     public static String socketPath() {
-        String os = System.getProperty("os.name", "").toLowerCase();
-        if (os.contains("win")) return "\\\\.\\pipe\\docker_engine";
-        return System.getenv().getOrDefault("DOCKER_SOCK", "/var/run/docker.sock");
+        return dockerHost().socketPath();
+    }
+
+    /**
+     * The {@code docker run} arguments needed to give a container access to the host
+     * Docker daemon. Unix sockets are bind-mounted at the canonical in-container path;
+     * remote TCP daemons are passed through via {@code DOCKER_HOST}.
+     */
+    public static List<String> dockerSocketRunArgs() {
+        DockerHost host = dockerHost();
+        return switch (host.kind()) {
+            case TCP -> List.of("-e", "DOCKER_HOST=" + host.raw());
+            case UNIX -> List.of("-v", host.socketPath() + ":" + DEFAULT_UNIX_SOCKET);
+            case NPIPE -> List.of("-v", DEFAULT_UNIX_SOCKET + ":" + DEFAULT_UNIX_SOCKET);
+        };
     }
 }

src/main/java/io/floci/cli/doctor/checks/DockerSocketCheck.java

@@ -11,17 +11,23 @@ public class DockerSocketCheck implements Check {
 
     @Override
     public CheckResult run(String endpoint, String container) {
-        String socketPath = DockerClient.socketPath();
-        String os = System.getProperty("os.name", "").toLowerCase();
-        if (os.contains("win")) {
-            return CheckResult.ok("docker.socket", "Windows named pipe (" + socketPath + ")");
+        DockerClient.DockerHost host = DockerClient.dockerHost();
+        switch (host.kind()) {
+            case NPIPE:
+                return CheckResult.ok("docker.socket", "Windows named pipe (" + host.socketPath() + ")");
+            case TCP:
+                return CheckResult.ok("docker.socket", "remote daemon (" + host.raw() + ")");
+            default:
+                break;
         }
+        String socketPath = host.socketPath();
         if (Files.exists(Path.of(socketPath))) {
             return CheckResult.ok("docker.socket", socketPath + " accessible");
         }
+        String os = System.getProperty("os.name", "").toLowerCase();
         String fix = os.contains("mac")
                 ? "Open Docker Desktop — the socket is created when Docker Desktop is running"
-                : "sudo chmod 666 /var/run/docker.sock  OR  add your user to the docker group";
+                : "sudo chmod 666 " + socketPath + "  OR  add your user to the docker group";
         return CheckResult.fail("docker.socket", socketPath + " not found or not accessible", fix);
     }
 }

src/test/java/io/floci/cli/unit/DockerHostResolveTest.java

@@ -0,0 +1,84 @@
+package io.floci.cli.unit;
+
+import io.floci.cli.docker.DockerClient;
+import io.floci.cli.docker.DockerClient.DockerHost;
+import io.floci.cli.docker.DockerClient.Kind;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class DockerHostResolveTest {
+
+    @Test
+    void rootlessPodmanUnixSocket() {
+        DockerHost h = DockerClient.parseDockerHost(
+                "unix:///run/user/1000/podman/podman.sock", null, "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/run/user/1000/podman/podman.sock", h.socketPath());
+    }
+
+    @Test
+    void rootfulDockerUnixSocket() {
+        DockerHost h = DockerClient.parseDockerHost("unix:///var/run/docker.sock", null, "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/var/run/docker.sock", h.socketPath());
+    }
+
+    @Test
+    void remoteTcpDaemon() {
+        DockerHost h = DockerClient.parseDockerHost("tcp://10.0.0.1:2375", null, "Linux");
+        assertEquals(Kind.TCP, h.kind());
+        assertNull(h.socketPath());
+        assertEquals("tcp://10.0.0.1:2375", h.raw());
+    }
+
+    @Test
+    void barePathTreatedAsUnixSocket() {
+        DockerHost h = DockerClient.parseDockerHost("/run/user/1000/podman/podman.sock", null, "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/run/user/1000/podman/podman.sock", h.socketPath());
+    }
+
+    @Test
+    void npipeScheme() {
+        DockerHost h = DockerClient.parseDockerHost("npipe:////./pipe/podman", null, "Windows 11");
+        assertEquals(Kind.NPIPE, h.kind());
+        assertEquals("//./pipe/podman", h.socketPath());
+    }
+
+    @Test
+    void dockerHostTakesPrecedenceOverDockerSock() {
+        DockerHost h = DockerClient.parseDockerHost(
+                "unix:///run/podman/podman.sock", "/var/run/docker.sock", "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/run/podman/podman.sock", h.socketPath());
+    }
+
+    @Test
+    void fallsBackToDockerSock() {
+        DockerHost h = DockerClient.parseDockerHost(null, "/custom/docker.sock", "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/custom/docker.sock", h.socketPath());
+    }
+
+    @Test
+    void blankEnvIgnored() {
+        DockerHost h = DockerClient.parseDockerHost("  ", "  ", "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/var/run/docker.sock", h.socketPath());
+    }
+
+    @Test
+    void defaultLinuxSocket() {
+        DockerHost h = DockerClient.parseDockerHost(null, null, "Linux");
+        assertEquals(Kind.UNIX, h.kind());
+        assertEquals("/var/run/docker.sock", h.socketPath());
+    }
+
+    @Test
+    void defaultWindowsPipe() {
+        DockerHost h = DockerClient.parseDockerHost(null, null, "Windows 11");
+        assertEquals(Kind.NPIPE, h.kind());
+        assertEquals("\\\\.\\pipe\\docker_engine", h.socketPath());
+    }
+}