feat(core): support TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX

core/testcontainers/core/config.py

@@ -108,11 +108,12 @@ def _render_bool(self, env_name: str, prop_name: str) -> bool:
     _docker_auth_config: Optional[str] = field(default_factory=lambda: environ.get("DOCKER_AUTH_CONFIG"))
     tc_host_override: Optional[str] = environ.get("TC_HOST", environ.get("TESTCONTAINERS_HOST_OVERRIDE"))
     connection_mode_override: Optional[ConnectionMode] = field(default_factory=get_user_overwritten_connection_mode)
-
     """
     https://github.com/testcontainers/testcontainers-go/blob/dd76d1e39c654433a3d80429690d07abcec04424/docker.go#L644
     if os env TC_HOST is set, use it
     """
+    hub_image_name_prefix: str = environ.get("TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX", "")
+    """ Prefix to use for hub image names, e.g. for private registries. """
 
     @property
     def docker_auth_config(self) -> Optional[str]:

core/testcontainers/core/container.py

@@ -1,6 +1,6 @@
 import contextlib
 import sys
-from os import PathLike
+from os import PathLike, getenv
 from socket import socket
 from types import TracebackType
 from typing import TYPE_CHECKING, Any, Optional, TypedDict, Union, cast
@@ -81,7 +81,7 @@ def __init__(
             for vol in volumes:
                 self.with_volume_mapping(*vol)
 
-        self.image = image
+        self.image = c.hub_image_name_prefix + image
         self._docker = DockerClient(**(docker_client_kw or {}))
         self._container: Optional[Container] = None
         self._command: Optional[Union[str, list[str]]] = command

core/tests/test_config.py

@@ -27,7 +27,14 @@ def test_read_tc_properties(monkeypatch: MonkeyPatch) -> None:
         config = TCC()
         assert config.tc_properties == {"tc.host": "some_value"}
 
-
+def test_hub_image_name_prefix(monkeypatch: MonkeyPatch) -> None:
+    """
+    Ensure that the hub_image_name_prefix configuration variable can be read from the environment
+    """
+    monkeypatch.setenv("TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX", "myregistry.local/")
+    config = TCC()
+    assert config.hub_image_name_prefix == "myregistry.local/"
+
 def test_set_tc_properties(monkeypatch: MonkeyPatch) -> None:
     """
     Ensure the configuration file variables can be read if no environment variable is set

core/tests/test_container.py

@@ -3,6 +3,7 @@
 from testcontainers.core.container import DockerContainer
 from testcontainers.core.docker_client import DockerClient
 from testcontainers.core.config import ConnectionMode
+from testcontainers.core.config import testcontainers_config
 
 FAKE_ID = "ABC123"
 
@@ -96,3 +97,25 @@ def test_attribute(init_attr, init_value, class_attr, stored_value):
     """Test that the attributes set through the __init__ function are properly stored."""
     with DockerContainer("ubuntu", **{init_attr: init_value}) as container:
         assert getattr(container, class_attr) == stored_value
+
+
+def test_image_prefix_applied(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that the hub_image_name_prefix is properly applied to the image name."""
+
+    # Set a prefix
+    test_prefix = "myregistry.example.com/"
+    monkeypatch.setattr(testcontainers_config, "hub_image_name_prefix", test_prefix)
+
+    # Create a container and verify the prefix is applied
+    container = DockerContainer("nginx:latest")
+    assert container.image == "myregistry.example.com/nginx:latest"
+
+
+def test_image_no_prefix_applied_when_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that when hub_image_name_prefix is empty, no prefix is applied."""
+    # Set an empty prefix
+    monkeypatch.setattr(testcontainers_config, "hub_image_name_prefix", "")
+
+    # Create a container and verify no prefix is applied
+    container = DockerContainer("nginx:latest")
+    assert container.image == "nginx:latest"