1. Help Center
  2. Network Configuration

How to use Testcontainers Cloud with internal Docker registries?

Instructions for users who need to pull images from a ‘private’ registry that is not accessible from the public internet. Docker Hub, Amazon ECR, GCR, etc users *do not* need to use this feature, as these registries are exposed to the public internet

This feature requires version v1.4.1+ of the Testcontainers Cloud Desktop/agent application. 

Testcontainers Cloud Desktop usage:

Set per-user configuration in the ~/.testcontainers.properties file:

cloud.private_registry.proxy.url = https://private.registry.example.com:8999

It's possible to configure more than one registry:

cloud.private_registry.proxy.url = https://private.registry.example.com:8999
cloud.private_registry.proxy.url.second = https://private2.registry.example.com:8999
cloud.private_registry.proxy.url.test = https://test.registry.example.com:8999

The part after .url. has to be unique, however, used only for convenience, so could be anything

Enable images such as private.registry.example.com:8999/prefix/name to be pulled:

cloud.private_registry.proxy.allowed_image_name_globs = **

Or more precisely:

cloud.private_registry.proxy.allowed_image_name_globs = prefix/*,prefix/name

define this way comma-separated list of globs for images allow-listed for pulls (** means all). We would recommend that you keep the allowed list as small as possible.

It's possible to ignore certificate-related issues with the:

cloud.private_registry.proxy.insecure_skip_verify = true

This is not recommended, as allows MitM attacks, however, could be used for testing purposes in case of connection issues.

Updates will be loaded on startup so you need to Restart the Testcontainers Cloud application

Agent CLI usage:

Add flags to the CLI invocation (the flag can be specified for each registry you want to enable):

--private-registry-url=https://private.registry.example.com:8999 --private-registry-url=https://private2.registry.example.com:8999

Enable images such as private.registry.example.com:8999/prefix/name or private.registry.example.com:8999/name to be pulled.

--private-registry-allowed-image-name-globs=** 

Or more precisely:

--private-registry-allowed-image-name-globs=prefix/*,prefix/name

define this way comma-separated list of globs for images allow-listed for pulls (** means all). We would recommend that you keep the allowed list as small as possible.

Current limitations:

  • Image pull is supported, but the push will be prevented.
  • Proxying must be configured on a per-machine basis, but we expect this to be configurable organisation-wide later
  • Credentials/tokens for all public/private docker registries are visible to the Testcontainers library and Testcontainers Cloud (data is proxied but not stored).
  • Images pulled from private registries are cached within users’ Testcontainers Cloud VM, which is deleted automatically after being idle for approximately 30 minutes.

💡 As security measures, the agent will only allow proxying to a single configured registry host, restricts HTTP verbs to HEAD/GET, and only will enable requests which match an allowlist of paths (the path allowlist is based on the images which the agent is configured to allow).

At present these settings are configured on a per-installation basis, but we expect these to become centrally configurable at a later date.