Advanced options

Container labels

To add a custom label to the container, use withLabel:

Adding a single label

public GenericContainer containerWithLabel = new GenericContainer(DockerImageName.parse("alpine:3.17"))
    .withLabel("key", "value");

Additionally, multiple labels may be applied together from a map:

Adding multiple labels

private Map<String, String> mapOfLabels = new HashMap<>();
// populate map, e.g. mapOfLabels.put("key1", "value1");

public GenericContainer containerWithMultipleLabels = new GenericContainer(DockerImageName.parse("alpine:3.17"))
    .withLabels(mapOfLabels);

Image Pull Policy

By default, the container image is retrieved from the local Docker images cache. This works well when running against a specific version, but for images with a static tag (i.e. 'latest') this may lead to a newer version not being pulled.

It is possible to specify an Image Pull Policy to determine at runtime whether an image should be pulled or not:

Setting image pull policy

GenericContainer<?> container = new GenericContainer<>(imageName)
    .withImagePullPolicy(PullPolicy.alwaysPull())

... or providing a function:

Custom image pull policy

GenericContainer<?> container = new GenericContainer<>(imageName)
    .withImagePullPolicy(
        new AbstractImagePullPolicy() {
            @Override
            protected boolean shouldPullCached(DockerImageName imageName, ImageData localImageData) {
                return System.getenv("ALWAYS_PULL_IMAGE") != null;
            }
        }
    )

You can also configure Testcontainers to use your custom implementation by using pull.policy

src/test/resources/testcontainers.properties

pull.policy=com.mycompany.testcontainers.ExampleImagePullPolicy

You can also use the provided implementation to always pull images

src/test/resources/testcontainers.properties

pull.policy=org.testcontainers.images.AlwaysPullPolicy

Please see the documentation on configuration mechanisms for more information.

Customizing the container

Using docker-java

It is possible to use the docker-java API directly to customize containers before creation. This is useful if there is a need to use advanced Docker features that are not exposed by the Testcontainers API. Any customizations you make using withCreateContainerCmdModifier will be applied on top of the container definition that Testcontainers creates, but before it is created.

For example, this can be used to change the container hostname:

Using modifier to change hostname

@Rule
public GenericContainer theCache = new GenericContainer<>(DockerImageName.parse("redis:6-alpine"))
    .withCreateContainerCmdModifier(cmd -> cmd.withHostName("the-cache"));

... or modify container memory (see this if it does not appear to work):

Using modifier to change memory limits

private long memoryInBytes = 32l * 1024l * 1024l;

private long memorySwapInBytes = 64l * 1024l * 1024l;

@Rule
public GenericContainer memoryLimitedRedis = new GenericContainer<>(DockerImageName.parse("redis:6-alpine"))
    .withCreateContainerCmdModifier(cmd -> {
        cmd.getHostConfig()
            .withMemory(memoryInBytes)
            .withMemorySwap(memorySwapInBytes);
    });

Note

It is recommended to use this sparingly, and follow changes to the docker-java API if you choose to use this. It is typically quite stable, though.

For what is possible, consult the docker-java CreateContainerCmd source code.

Using CreateContainerCmdModifier

Testcontainers provides a CreateContainerCmdModifier to customize docker-java CreateContainerCmd via Service Provider Interface (SPI) mechanism.

CreateContainerCmd example implementation

package org.testcontainers.custom;

import com.github.dockerjava.api.command.CreateContainerCmd;
import org.testcontainers.core.CreateContainerCmdModifier;

import java.util.HashMap;
import java.util.Map;

public class TestCreateContainerCmdModifier implements CreateContainerCmdModifier {

    @Override
    public CreateContainerCmd modify(CreateContainerCmd createContainerCmd) {
        Map<String, String> labels = new HashMap<>();
        labels.put("project", "testcontainers-java");
        labels.put("scope", "global");
        createContainerCmd.getLabels().putAll(labels);
        return createContainerCmd;
    }
}

The previous implementation should be registered in META-INF/services/org.testcontainers.core.CreateContainerCmdModifier file.

Warning

CreateContainerCmdModifier implementation will apply to all containers created by Testcontainers.

Parallel Container Startup

Usually, containers are started sequentially when more than one container is used. Using Startables.deepStart(container1, container2, ...).join() will start all containers in parallel. This can be advantageous to reduce the impact of the container startup overhead.