1. OVERVIEW

I have shared how to use Testcontainers to run Spring Boot CosmosDB, and DynamoDB integration tests locally, meaning in your development workstation or laptop.

But what if for licensing reasons, or resources constraints you cannot install Docker Desktop?
What if your organization needs to share specialized testing environments not available locally?
What if your integration tests need to start 3rd party systems to connect to in dedicated build servers as part of your CI/CD pipeline?

This blog post walks you through how to configure a Docker host to allow remote connections, and Testcontainers to use a remote Docker host.

Connecting your Testcontainers integration tests to a remote Docker host

2. DOCKER HOST CONFIGURATION

Let’s enable the Docker Engine API in the remote Docker host.

• Create this folder if it’s not already in the remote Docker host:

sudo mkdir -p /etc/systemd/system/docker.service.d/

• Create or update /etc/systemd/system/docker.service.d/override.conf file with:

[Service]
 ExecStart=
 ExecStart=/usr/bin/dockerd --config-file /etc/docker/daemon.json -H unix:///var/run/docker.sock -H fd:// -H tcp://0.0.0.0:2375

The Docker host will not only listen for local connections via unix:///var/run/docker.sock, but will also listen for remote connections on tcp://0.0.0.0:2375.

• Reload the new configuration and restart the remote Docker host

sudo systemctl daemon-reload
sudo systemctl restart docker

The remote Docker host should now be available to process API requests on port 2375.

3. TESTCONTAINERS CLIENT CONFIGURATION

Let’s now update the Testcontainers configuration where the Integration Tests will run at.
This could be in your organization’s CI/CD servers, your team’s development workstations or laptops.

• Edit ~/.testcontainers.properties:

docker.client.strategy=org.testcontainers.dockerclient.EnvironmentAndSystemPropertyClientProviderStrategy
docker.host=tcp://<remote docker host>:2375

EnvironmentAndSystemPropertyClientProviderStrategy Testcontainers class allows the use of environment variables and system properties to try and locate a Docker environment.

In our case, Testcontainers will locate the remote Docker host via the docker.host configuration property.

4. RUNNING INTEGRATION TESTS

Let’s run the CustomerControllerIntegrationTest from the blog Provisioning DynamoDB tables and seeding data to run Spring Boot Integration Tests.

07:40:33.774 [main] INFO org.testcontainers.dockerclient.DockerClientProviderStrategy -- Found Docker environment with Environment variables, system properties and defaults. Resolved dockerHost=tcp://192.168.1.188:2375
07:40:33.912 [main] INFO org.testcontainers.DockerClientFactory -- Docker host IP address is 192.168.1.188
07:40:33.963 [main] INFO org.testcontainers.DockerClientFactory -- Connected to docker: 
  Server Version: 28.1.1
  API Version: 1.49
  Operating System: Debian GNU/Linux 12 (bookworm)
  Total Memory: 31893 MB
07:40:34.104 [main] INFO tc.testcontainers/ryuk:0.7.0 -- Creating container for image: testcontainers/ryuk:0.7.0
07:40:35.128 [main] INFO org.testcontainers.utility.RegistryAuthLocator -- Credential helper/store (docker-credential-desktop) does not have credentials for https://index.docker.io/v1/
07:40:35.325 [main] INFO tc.testcontainers/ryuk:0.7.0 -- Container testcontainers/ryuk:0.7.0 is starting: 6ac0ad585d42b0e3b7d7875d818e633a80d337d0060a07f97f5010ab4daaab83
07:40:35.623 [main] INFO tc.testcontainers/ryuk:0.7.0 -- Container testcontainers/ryuk:0.7.0 started in PT1.518985S
07:40:35.633 [main] INFO org.testcontainers.utility.RyukResourceReaper -- Ryuk started - will monitor and terminate Testcontainers containers on JVM exit
07:40:35.633 [main] INFO org.testcontainers.DockerClientFactory -- Checking the system...
07:40:35.634 [main] INFO org.testcontainers.DockerClientFactory -- ✔︎ Docker server version should be at least 1.6.0
07:40:35.654 [main] INFO tc.localstack/localstack:latest -- LOCALSTACK_HOST environment variable set to 192.168.1.188 (to match host-routable address for container)
07:40:35.655 [main] INFO tc.localstack/localstack:latest -- Creating container for image: localstack/localstack:latest
07:40:36.148 [main] INFO tc.localstack/localstack:latest -- Container localstack/localstack:latest is starting: c45978e54470370106a142b2333b239971aea3c2ed0e2728a00073ed38092018
07:40:38.320 [main] INFO tc.localstack/localstack:latest -- Container localstack/localstack:latest started in PT2.664644S
...

The integration test now uses a remote Docker host to run a LocalStack Docker container, according to the log:

Found Docker environment with Environment variables, system properties and defaults. Resolved dockerHost=tcp://asimio-nas.local:2375

5. CONCLUSION

This blog post helped you to configure both, a remote Docker host to allow remote connections, and Testcontainers for your integration tests to use a remote Docker host.

Running Testcontainers in a remote Docker host enhances your org’s testing capabilities.

Thanks for reading and as always, feedback is very much appreciated. If you found this post helpful and would like to receive updates when content like this gets published, sign up to the newsletter.

6. RELATED PRODUCTS

1. Buy Getting started with Spring Boot, DynamoDB, Spring Cloud AWS, and AWS Java SDK version 2. Write DynamoDB dynamic queries with DynamoDbTemplate. Seeding a DynamoDB table and run integration tests with Testcontainers, DynamoDB and Docker - Complete Source Code
2. Buy Getting started sending SNS notifications, publishing and consuming SQS messages with Spring Boot, Spring Cloud AWS, and AWS Java SDK version 2. Provision SNS topics, and SQS queues to run your Integration Tests with Testcontainers, LocalStack and Docker - Complete Source Code
3. Buy Seeding Cosmos DB Data and run integration tests with Testcontainers and Cosmos DB Docker emulator for Spring Boot applications - Complete Source Code

Your organization can now save time and costs by purchasing a working code base, clean implementation, with support for future revisions of any of these products.