feat(docker): Podman compatibility, multi-socket support, per-host error isolation (#5425)

Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>

packages/docker/src/env.ts

@@ -4,9 +4,11 @@ import { createBooleanSchema, createEnv } from "@homarr/core/infrastructure/env"
 
 export const env = createEnv({
   server: {
-    // Comma separated list of docker hostnames that can be used to connect to query the docker endpoints (localhost:2375,host.docker.internal:2375, ...)
+    // Comma separated list of docker hostnames that can be used to connect to query the docker endpoints (localhost,host.docker.internal, ...)
     DOCKER_HOSTNAMES: z.string().optional(),
     DOCKER_PORTS: z.string().optional(),
+    // Comma separated paths to Docker-compatible Unix sockets (e.g., /var/run/docker.sock,/run/user/1000/podman/podman.sock)
+    DOCKER_SOCKET_PATHS: z.string().optional(),
     ENABLE_DOCKER: createBooleanSchema(true),
     ENABLE_KUBERNETES: createBooleanSchema(false),
   },

packages/docker/src/singleton.ts

@@ -11,31 +11,43 @@ export class DockerSingleton {
   private static instances: DockerInstance[] | null = null;
 
   private createInstances() {
+    const socketPaths = env.DOCKER_SOCKET_PATHS;
     const hostVariable = env.DOCKER_HOSTNAMES;
     const portVariable = env.DOCKER_PORTS;
-    if (hostVariable === undefined || portVariable === undefined) {
+
+    // Socket instances from DOCKER_SOCKET_PATHS
+    const socketInstances: DockerInstance[] = socketPaths
+      ? socketPaths.split(",").map((socketPath) => ({
+          host: socketPath,
+          instance: new Docker({ socketPath }),
+        }))
+      : [];
+
+    // TCP instances from existing DOCKER_HOSTNAMES/DOCKER_PORTS
+    let tcpInstances: DockerInstance[] = [];
+    if (hostVariable !== undefined && portVariable !== undefined) {
+      const hostnames = hostVariable.split(",");
+      const ports = portVariable.split(",");
+
+      if (hostnames.length !== ports.length) {
+        throw new Error("The number of hosts and ports must match");
+      }
+
+      tcpInstances = hostnames.map((host, i) => ({
+        host: `${host}:${ports[i]}`,
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        instance: new Docker({ host, port: parseInt(ports[i]!, 10) }),
+      }));
+    }
+
+    const instances = [...socketInstances, ...tcpInstances];
+
+    // Default: local socket if nothing else configured
+    if (instances.length === 0) {
       return [{ host: "socket", instance: new Docker() }];
     }
-    const hostnames = hostVariable.split(",");
-    const ports = portVariable.split(",");
 
-    if (hostnames.length !== ports.length) {
-      throw new Error("The number of hosts and ports must match");
-    }
-
-    return hostnames.map((host, i) => {
-      // Check above ensures that ports[i] is not undefined
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const port = ports[i]!;
-
-      return {
-        host: `${host}:${port}`,
-        instance: new Docker({
-          host,
-          port: parseInt(port, 10),
-        }),
-      };
-    });
+    return instances;
   }
 
   public static findInstance(host: string): DockerInstance | undefined {

packages/docker/src/test/singleton.spec.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import { DockerSingleton } from "../singleton";
+
+const mockEnv = vi.hoisted(() => ({
+  DOCKER_SOCKET_PATHS: undefined as string | undefined,
+  DOCKER_HOSTNAMES: undefined as string | undefined,
+  DOCKER_PORTS: undefined as string | undefined,
+  ENABLE_DOCKER: true,
+  ENABLE_KUBERNETES: false,
+}));
+
+vi.mock("dockerode", () => {
+  return {
+    default: class MockDocker {
+      constructor(public opts?: Record<string, unknown>) {}
+    },
+  };
+});
+
+vi.mock("../env", () => ({
+  env: mockEnv,
+}));
+
+describe("DockerSingleton", () => {
+  beforeEach(() => {
+    // Reset singleton cache between tests
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+    (DockerSingleton as any).instances = null;
+
+    // Reset env to defaults
+    mockEnv.DOCKER_SOCKET_PATHS = undefined;
+    mockEnv.DOCKER_HOSTNAMES = undefined;
+    mockEnv.DOCKER_PORTS = undefined;
+  });
+
+  test("should return default socket when no env vars set", () => {
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(1);
+    expect(instances[0]?.host).toBe("socket");
+  });
+
+  test("should return TCP instances only when DOCKER_HOSTNAMES and DOCKER_PORTS set", () => {
+    mockEnv.DOCKER_HOSTNAMES = "remote-host";
+    mockEnv.DOCKER_PORTS = "2375";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(1);
+    expect(instances[0]?.host).toBe("remote-host:2375");
+  });
+
+  test("should return multiple TCP instances", () => {
+    mockEnv.DOCKER_HOSTNAMES = "host1,host2";
+    mockEnv.DOCKER_PORTS = "2375,2376";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.host).toBe("host1:2375");
+    expect(instances[1]?.host).toBe("host2:2376");
+  });
+
+  test("should throw when hostname and port counts do not match", () => {
+    mockEnv.DOCKER_HOSTNAMES = "host1,host2";
+    mockEnv.DOCKER_PORTS = "2375";
+
+    expect(() => DockerSingleton.getInstances()).toThrow("The number of hosts and ports must match");
+  });
+
+  test("should return socket instances when DOCKER_SOCKET_PATHS set", () => {
+    mockEnv.DOCKER_SOCKET_PATHS = "/var/run/docker.sock";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(1);
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+  });
+
+  test("should return multiple socket instances", () => {
+    mockEnv.DOCKER_SOCKET_PATHS = "/var/run/docker.sock,/run/user/1000/podman/podman.sock";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+    expect(instances[1]?.host).toBe("/run/user/1000/podman/podman.sock");
+  });
+
+  test("should combine socket and TCP instances", () => {
+    mockEnv.DOCKER_SOCKET_PATHS = "/var/run/docker.sock,/run/user/1000/podman/podman.sock";
+    mockEnv.DOCKER_HOSTNAMES = "remote-host";
+    mockEnv.DOCKER_PORTS = "2375";
+
+    const instances = DockerSingleton.getInstances();
+
+    expect(instances).toHaveLength(3);
+    expect(instances[0]?.host).toBe("/var/run/docker.sock");
+    expect(instances[1]?.host).toBe("/run/user/1000/podman/podman.sock");
+    expect(instances[2]?.host).toBe("remote-host:2375");
+  });
+
+  test("should cache instances on subsequent calls", () => {
+    const first = DockerSingleton.getInstances();
+    const second = DockerSingleton.getInstances();
+
+    expect(first).toBe(second);
+  });
+});