feat(core): auto-detect DOCKER_HOST from current docker context (#1026)

Fall back to the active docker context's host (via
docker.context.ContextAPI) when neither tc.host nor DOCKER_HOST is set.

Closes #1025

Author: Tranquility2

core/testcontainers/core/docker_client.py

@@ -22,6 +22,7 @@
 from typing import TYPE_CHECKING, Any, Callable, Optional, TypeVar, Union, cast
 
 import docker
+from docker.context import ContextAPI
 from docker.models.containers import Container, ContainerCollection
 from docker.models.images import Image, ImageCollection
 from typing_extensions import ParamSpec
@@ -320,12 +321,33 @@ def get_container_inspect_info(self, container_id: str) -> "ContainerInspectInfo
 
 
 def get_docker_host() -> Optional[str]:
-    host = c.tc_properties_get_tc_host() or os.getenv("DOCKER_HOST")
+    host = c.tc_properties_get_tc_host() or os.getenv("DOCKER_HOST") or _get_docker_host_from_context()
     if host:
         return _sanitize_docker_host(host)
     return None
 
 
+def _get_docker_host_from_context() -> Optional[str]:
+    """
+    Look up the docker host from the current docker context (e.g. as set by``docker context use``).
+    This allows users with a remote docker host configured via docker contexts to use testcontainers
+    without having to additionally export ``DOCKER_HOST``.
+    """
+    try:
+        context = ContextAPI.get_current_context()
+    except Exception as e:
+        LOGGER.debug(f"failed to read current docker context: {e}")
+        return None
+    if context is None:
+        return None
+    host = context.Host
+    # The default context points at the local unix socket / named pipe; let
+    # docker-py fall back to its own defaults in that case.
+    if not host or context.Name == "default":
+        return None
+    return cast("str", host)
+
+
 def get_docker_host_hostname() -> Optional[str]:
     """Extract the remote hostname from an SSH-based DOCKER_HOST.
 

core/tests/test_docker_client.py

@@ -338,6 +338,7 @@ def test_get_docker_host_hostname(monkeypatch: pytest.MonkeyPatch, docker_host:
     from testcontainers.core.docker_client import get_docker_host_hostname
 
     monkeypatch.setattr(c, "tc_properties_get_tc_host", lambda: None)
+    monkeypatch.setattr("testcontainers.core.docker_client._get_docker_host_from_context", lambda: None)
     if docker_host:
         monkeypatch.setenv("DOCKER_HOST", docker_host)
     else:
@@ -355,3 +356,55 @@ def test_ssh_docker_host(monkeypatch: pytest.MonkeyPatch) -> None:
         client = DockerClient()
     mock_docker.from_env.assert_called_once_with(use_ssh_client=True)
     assert client.host() == "10.0.0.1"
+
+
+def _mock_docker_context(name: str, host: str) -> MagicMock:
+    context = MagicMock()
+    context.Name = name
+    context.Host = host
+    return context
+
+
+@pytest.mark.parametrize(
+    "context, expected",
+    [
+        pytest.param(_mock_docker_context("remote", "ssh://user@10.0.0.1"), "ssh://user@10.0.0.1", id="returns_host"),
+        pytest.param(
+            _mock_docker_context("default", "unix:///var/run/docker.sock"), None, id="default_context_skipped"
+        ),
+        pytest.param(_mock_docker_context("remote", ""), None, id="empty_host_returns_none"),
+        pytest.param(None, None, id="no_current_context"),
+    ],
+)
+def test_get_docker_host_from_context(monkeypatch: pytest.MonkeyPatch, context, expected) -> None:
+    from testcontainers.core.docker_client import _get_docker_host_from_context
+
+    monkeypatch.setattr(
+        "testcontainers.core.docker_client.ContextAPI.get_current_context",
+        lambda: context,
+    )
+    assert _get_docker_host_from_context() == expected
+
+
+def test_get_docker_host_from_context_swallows_errors(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A malformed docker config should not crash; we fall through to None."""
+    from testcontainers.core.docker_client import _get_docker_host_from_context
+
+    def _raise() -> None:
+        raise RuntimeError("broken docker config")
+
+    monkeypatch.setattr("testcontainers.core.docker_client.ContextAPI.get_current_context", _raise)
+    assert _get_docker_host_from_context() is None
+
+
+def test_get_docker_host_falls_back_to_context(monkeypatch: pytest.MonkeyPatch) -> None:
+    """When tc.host and DOCKER_HOST are unset, the current docker context wins."""
+    from testcontainers.core.docker_client import get_docker_host
+
+    monkeypatch.setattr(c, "tc_properties_get_tc_host", lambda: None)
+    monkeypatch.delenv("DOCKER_HOST", raising=False)
+    monkeypatch.setattr(
+        "testcontainers.core.docker_client.ContextAPI.get_current_context",
+        lambda: _mock_docker_context("remote", "ssh://user@10.0.0.1"),
+    )
+    assert get_docker_host() == "ssh://user@10.0.0.1"

docs/features/configuration.md

@@ -70,18 +70,21 @@ However, sometimes customization is required. Testcontainers-Python will respect
 3. Read the **DOCKER_HOST** environment variable. E.g. `DOCKER_HOST=unix:///var/run/docker.sock`
    See [Docker environment variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) for more information.
 
-4. Read the default Docker socket path, without the unix schema. E.g. `/var/run/docker.sock`
+4. Read the **current Docker context** (as set by `docker context use`) and use its host. E.g. with a context pointing at `ssh://user@remote-host`, no extra configuration is needed.
+   The built-in `default` context is skipped so local sockets / named pipes go through the standard fallback.
 
-5. Read the **docker.host** property in the `~/.testcontainers.properties` file. E.g. `docker.host=tcp://my.docker.host:1234`
+5. Read the default Docker socket path, without the unix schema. E.g. `/var/run/docker.sock`
 
-6. Read the rootless Docker socket path, checking the following alternative locations:
+6. Read the **docker.host** property in the `~/.testcontainers.properties` file. E.g. `docker.host=tcp://my.docker.host:1234`
+
+7. Read the rootless Docker socket path, checking the following alternative locations:
 
    1. `${XDG_RUNTIME_DIR}/.docker/run/docker.sock`
    2. `${HOME}/.docker/run/docker.sock`
    3. `${HOME}/.docker/desktop/docker.sock`
    4. `/run/user/${UID}/docker.sock`, where `${UID}` is the user ID of the current user
 
-7. The library will raise a `DockerHostError` if none of the above are set, meaning that the Docker host was not detected.
+8. The library will raise a `DockerHostError` if none of the above are set, meaning that the Docker host was not detected.
 
 ## Docker Socket Path Detection