Support Podman fallback when Docker is unavailable

Author: nezhar

docs/quickstart.md

@@ -7,10 +7,12 @@
 
 ### Using Podman instead of Docker
 
-VibePod auto-detects rootless Podman and applies the necessary user-namespace
-settings (`keep-id`) so workspace file permissions work correctly.
+VibePod auto-detects common Podman sockets when Docker is unavailable,
+and applies the necessary rootless user-namespace settings (`keep-id`) so
+workspace file permissions work correctly.
 
-Point VibePod at the Podman socket by setting `DOCKER_HOST`:
+If your Podman socket lives somewhere else, point VibePod at it by setting
+`DOCKER_HOST`:
 
 ```bash
 export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock

src/vibepod/core/docker.py

@@ -123,6 +123,45 @@ def _version_is_podman(version: Any) -> bool:
     return "podman" in str(version.get("Name", "")).lower()
 
 
+def _default_podman_socket_candidates() -> list[Path]:
+    """Return common Podman Docker-compatible API socket paths."""
+    candidates: list[Path] = []
+
+    xdg_runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "").strip()
+    if xdg_runtime_dir:
+        candidates.append(Path(xdg_runtime_dir) / "podman" / "podman.sock")
+
+    getuid = getattr(os, "getuid", None)
+    if callable(getuid):
+        candidates.append(Path("/run/user") / str(getuid()) / "podman" / "podman.sock")
+
+    candidates.append(Path("/run/podman/podman.sock"))
+
+    seen: set[str] = set()
+    unique: list[Path] = []
+    for candidate in candidates:
+        key = str(candidate)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(candidate)
+    return unique
+
+
+def _format_podman_socket_hint() -> str:
+    candidates = ", ".join(f"unix://{path}" for path in _default_podman_socket_candidates())
+    if shutil.which("podman"):
+        return (
+            " Podman appears to be installed, but VibePod could not connect to its "
+            "Docker-compatible socket. Start the Podman socket or set DOCKER_HOST "
+            f"to one of: {candidates}."
+        )
+    return (
+        " Install/start Docker, or install Podman and expose its Docker-compatible socket "
+        f"with DOCKER_HOST (for example: {candidates})."
+    )
+
+
 def _parse_image_name(image: str) -> tuple[str, str | None]:
     """Parse a full image string into repository and tag/digest."""
     if "@" in image:
@@ -141,13 +180,33 @@ class DockerManager:
     def __init__(self) -> None:
         if docker is None:
             raise DockerClientError("Docker SDK not installed")
+
+        self._rootless_podman: bool | None = None
         try:
             self.client = docker.from_env()
             self.client.ping()
         except DockerException as exc:
-            raise DockerClientError(f"Docker is not available: {exc}") from exc
-
-        self._rootless_podman: bool | None = None
+            podman_errors: list[str] = []
+            docker_client = getattr(docker, "DockerClient", None)
+            if callable(docker_client):
+                for socket_path in _default_podman_socket_candidates():
+                    if not socket_path.exists():
+                        continue
+                    base_url = f"unix://{socket_path}"
+                    try:
+                        client = docker_client(base_url=base_url, version="auto")
+                        client.ping()
+                    except DockerException as podman_exc:
+                        podman_errors.append(f"{base_url}: {podman_exc}")
+                        continue
+                    self.client = client
+                    return
+
+            message = f"Docker is not available: {exc}"
+            if podman_errors:
+                message += " Podman socket attempts failed: " + "; ".join(podman_errors) + "."
+            message += _format_podman_socket_hint()
+            raise DockerClientError(message) from exc
 
     def is_rootless_podman(self) -> bool:
         """Return True for a rootless Podman engine exposed through the Docker API."""

tests/test_docker.py

@@ -10,6 +10,7 @@
 from vibepod.core.docker import (
     APIError,
     DockerClientError,
+    DockerException,
     DockerManager,
     NotFound,
     _parse_image_name,
@@ -33,6 +34,58 @@ def test_parse_image_name() -> None:
     assert _parse_image_name("ubuntu") == ("ubuntu", None)
 
 
+@patch("vibepod.core.docker.docker")
+def test_docker_manager_falls_back_to_default_rootless_podman_socket(
+    mock_docker, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    default_client = MagicMock()
+    default_client.ping.side_effect = DockerException("default Docker socket missing")
+    podman_client = MagicMock()
+    mock_docker.from_env.return_value = default_client
+    mock_docker.DockerClient.return_value = podman_client
+
+    runtime_dir = tmp_path / "runtime"
+    podman_socket = runtime_dir / "podman" / "podman.sock"
+    podman_socket.parent.mkdir(parents=True)
+    podman_socket.touch()
+    monkeypatch.delenv("DOCKER_HOST", raising=False)
+    monkeypatch.setenv("XDG_RUNTIME_DIR", str(runtime_dir))
+
+    manager = DockerManager()
+
+    assert manager.client is podman_client
+    mock_docker.DockerClient.assert_called_once_with(
+        base_url=f"unix://{podman_socket}", version="auto"
+    )
+    podman_client.ping.assert_called_once_with()
+
+
+@patch("vibepod.core.docker.docker")
+def test_docker_manager_falls_back_to_podman_when_docker_host_points_to_missing_docker(
+    mock_docker, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    default_client = MagicMock()
+    default_client.ping.side_effect = DockerException("configured Docker socket missing")
+    podman_client = MagicMock()
+    mock_docker.from_env.return_value = default_client
+    mock_docker.DockerClient.return_value = podman_client
+
+    runtime_dir = tmp_path / "runtime"
+    podman_socket = runtime_dir / "podman" / "podman.sock"
+    podman_socket.parent.mkdir(parents=True)
+    podman_socket.touch()
+    monkeypatch.setenv("DOCKER_HOST", "unix:///var/run/docker.sock")
+    monkeypatch.setenv("XDG_RUNTIME_DIR", str(runtime_dir))
+
+    manager = DockerManager()
+
+    assert manager.client is podman_client
+    mock_docker.DockerClient.assert_called_once_with(
+        base_url=f"unix://{podman_socket}", version="auto"
+    )
+    podman_client.ping.assert_called_once_with()
+
+
 @patch("vibepod.core.docker.docker")
 def test_pull_image_success(mock_docker) -> None:
     # Set up mocks for DockerManager initialization