Add support for image registry substitution via environment variable (#729)

Author: silh

docs/configuration.md

@@ -5,8 +5,8 @@ All possible environment variable configurations for Testcontainers are found he
 ## Logs
 
 | Variable | Example                   | Description                |
-|----------|---------------------------|----------------------------|
-| DEBUG    | testcontainers*           | Enable all logs            |
+| -------- | ------------------------- | -------------------------- |
+| DEBUG    | testcontainers\*          | Enable all logs            |
 | DEBUG    | testcontainers            | Enable testcontainers logs |
 | DEBUG    | testcontainers:containers | Enable container logs      |
 | DEBUG    | testcontainers:compose    | Enable compose logs        |
@@ -20,25 +20,26 @@ Note that you can enable multiple loggers, e.g: `DEBUG=testcontainers,testcontai
 
 Configuration of the Docker daemon:
 
-| Variable           | Example                                                            | Description                                                                             |
-|--------------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
-| DOCKER_HOST        | tcp://docker:2375                                                  | Set the URL of the docker daemon                                                        |
-| DOCKER_TLS_VERIFY  | 1                                                                  | Enable/disable TLS communication with the docker daemon                                 |
-| DOCKER_CERT_PATH   | /some/path                                                         | Configures the path to the files used for TLS verification                              |
-| DOCKER_CONFIG      | /some/path                                                         | Configures the path to the config.json file for authentication                          |
+| Variable           | Example                                                                    | Description                                                                             |
+| ------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| DOCKER_HOST        | tcp://docker:2375                                                          | Set the URL of the docker daemon                                                        |
+| DOCKER_TLS_VERIFY  | 1                                                                          | Enable/disable TLS communication with the docker daemon                                 |
+| DOCKER_CERT_PATH   | /some/path                                                                 | Configures the path to the files used for TLS verification                              |
+| DOCKER_CONFIG      | /some/path                                                                 | Configures the path to the config.json file for authentication                          |
 | DOCKER_AUTH_CONFIG | `{"auths":{"https://registry.example.com":{"username":"","password":""}}}` | JSON string representation of the config.json file, takes precedence for authentication |
 
 ## Testcontainers
 
 Configuration of Testcontainers and its behaviours:
 
 | Variable                              | Example                   | Description                              |
-|---------------------------------------|---------------------------|------------------------------------------|
+| ------------------------------------- | ------------------------- | ---------------------------------------- |
 | TESTCONTAINERS_HOST_OVERRIDE          | tcp://docker:2375         | Docker's host on which ports are exposed |
 | TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE | /var/run/docker.sock      | Path to Docker's socket used by ryuk     |
 | TESTCONTAINERS_RYUK_PRIVILEGED        | true                      | Run ryuk as a privileged container       |
 | TESTCONTAINERS_RYUK_DISABLED          | true                      | Disable ryuk                             |
 | TESTCONTAINERS_RYUK_PORT              | 65515                     | Set ryuk host port (not recommended)     |
 | TESTCONTAINERS_SSHD_PORT              | 65515                     | Set SSHd host port (not recommended)     |
+| TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX  | mycompany.com/registry    | Set default image registry               |
 | RYUK_CONTAINER_IMAGE                  | testcontainers/ryuk:0.5.1 | Custom image for ryuk                    |
 | SSHD_CONTAINER_IMAGE                  | testcontainers/sshd:1.1.0 | Custom image for SSHd                    |

docs/features/images.md

@@ -90,3 +90,14 @@ const container = await GenericContainer
   .withCache(false)
   .build();
 ```
+
+## Image name substitution
+
+Testcontainers supports automatic substitution of Docker image names.
+
+This allows replacement of an image name specified in test code with an alternative name - for example, to replace the name of a Docker Hub image dependency with an alternative hosted on a private image registry.
+
+This is advisable to avoid Docker Hub rate limiting, and some companies will prefer this for policy reasons.
+
+You can then configure Testcontainers to apply the prefix `registry.mycompany.com/mirror/` to every image that it tries to pull from Docker Hub. This can be done by setting the environment variable `TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX=registry.mycompany.com/mirror/`.
+

packages/testcontainers/src/container-runtime/image-name.test.ts

@@ -53,6 +53,21 @@ describe("ContainerImage", () => {
       );
       expect(imageName.string).toBe("aa285b773a2c042056883845aea893a743d358a5d40f61734fa228fde93dae6f:1");
     });
+
+    it("should substitute no registry with the one provided via TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX", () => {
+      const oldEnvValue = process.env.TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX;
+      try {
+        process.env.TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX = "custom.com/registry";
+        const imageName = new ImageName(undefined, "image", "tag");
+        expect(imageName.string).toBe("custom.com/registry/image:tag");
+      } finally {
+        if (oldEnvValue === undefined) {
+          delete process.env.TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX;
+        } else {
+          process.env.TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX = oldEnvValue;
+        }
+      }
+    });
   });
 
   describe("fromString", () => {

packages/testcontainers/src/container-runtime/image-name.ts

@@ -1,3 +1,5 @@
+import { log } from "../common";
+
 export class ImageName {
   public readonly string: string;
 
@@ -8,6 +10,12 @@ export class ImageName {
     public readonly image: string,
     public readonly tag: string
   ) {
+    if (!this.registry) {
+      this.registry = process.env.TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX;
+      if (this.registry) {
+        log.info(`Applying changes to image ${image} with tag ${tag}: added registry ${this.registry}`);
+      }
+    }
     if (this.registry) {
       if (this.tag.startsWith("sha256:")) {
         this.string = `${this.registry}/${this.image}@${this.tag}`;