Docker Client Management

/**
 * Factory for creating Docker clients with automatic configuration.
 * Singleton instance provides centralized Docker client management.
 * Constructor is package-private. Use instance() to access singleton.
 */
public class DockerClientFactory {
    /**
     * Get the singleton factory instance.
     *
     * @return the factory instance
     */
    public static DockerClientFactory instance();

    /**
     * Get the Docker client.
     * Lazily initializes and caches the client.
     *
     * @return configured Docker client
     */
    public DockerClient client();

    /**
     * Get a lazy-initialized Docker client.
     * This is a static convenience method that returns a client initialized only on first use.
     * Prefer using instance().client() in most cases for better control over lifecycle.
     * Use this method when you need a simple static access pattern.
     *
     * @return lazy Docker client
     */
    public static DockerClient lazyClient();

    /**
     * Check if Docker is available and accessible.
     *
     * @return true if Docker can be accessed
     */
    public boolean isDockerAvailable();

    /**
     * Get the Docker host IP address.
     * Returns the host where containers can be accessed from tests.
     *
     * @return Docker host IP address
     */
    public String dockerHostIpAddress();

    /**
     * Get the active Docker API version.
     *
     * @return Docker API version string
     */
    public String getActiveApiVersion();

    /**
     * Get the active execution driver.
     *
     * @return execution driver name
     */
    public String getActiveExecutionDriver();

    /**
     * Check if file mounting is supported in the current Docker environment.
     *
     * @return true if file mounting is supported
     */
    public boolean isFileMountingSupported();

    /**
     * Get Docker daemon information.
     * WARNING: This is marked as unstable API and may change in future releases.
     * The API structure and behavior may be modified without notice.
     * Use with caution in production code.
     *
     * @return Docker info object
     */
    @UnstableAPI
    public com.github.dockerjava.api.model.Info getInfo();

    /**
     * Get the remote Docker Unix socket path.
     * Marked as unstable API.
     *
     * @return Unix socket path, or null if not applicable
     */
    @UnstableAPI
    public String getRemoteDockerUnixSocketPath();

    /**
     * Get the transport configuration.
     * Marked as unstable API.
     *
     * @return transport configuration
     */
    @UnstableAPI
    public TransportConfig getTransportConfig();

    /**
     * Run a block of code inside a Docker container with custom configuration.
     * This is an advanced method for executing code within a container context.
     *
     * @param <T> return type
     * @param createContainerCmdConsumer consumer to customize container creation command
     * @param block function to execute - receives docker client and container ID, returns result
     * @return result from the block execution
     */
    public <T> T runInsideDocker(
        Consumer<CreateContainerCmd> createContainerCmdConsumer,
        BiFunction<DockerClient, String, T> block
    );

    /**
     * Check if a specific Docker client provider strategy is being used.
     *
     * @param providerStrategyClass provider strategy class to check
     * @return true if the strategy is active
     */
    public boolean isUsing(Class<? extends DockerClientProviderStrategy> providerStrategyClass);

    /**
     * Check and pull a Docker image.
     * Deprecated - use ImagePullPolicy instead.
     *
     * @param client Docker client
     * @param image image name to pull
     * @deprecated Use ImagePullPolicy for image pulling
     */
    @Deprecated
    public void checkAndPullImage(DockerClient client, String image);

    // Constants
    /** Thread group for Testcontainers threads */
    public static final ThreadGroup TESTCONTAINERS_THREAD_GROUP;

    /** Label applied to all Testcontainers resources */
    public static final String TESTCONTAINERS_LABEL = "org.testcontainers";

    /** Session ID label for resource tracking */
    public static final String TESTCONTAINERS_SESSION_ID_LABEL = "org.testcontainers.session-id";

    /** Language label for tracking client language */
    public static final String TESTCONTAINERS_LANG_LABEL = "org.testcontainers.lang";

    /** Version label for tracking Testcontainers version */
    public static final String TESTCONTAINERS_VERSION_LABEL = "org.testcontainers.version";

    /** Unique session ID for this JVM instance */
    public static final String SESSION_ID;

    /** Testcontainers version */
    public static final String TESTCONTAINERS_VERSION;

    /** Default labels applied to all resources */
    public static final Map<String, String> DEFAULT_LABELS;
}

import org.testcontainers.DockerClientFactory;
import com.github.dockerjava.api.DockerClient;

// Get Docker client
DockerClient client = DockerClientFactory.instance().client();

// Check Docker availability
if (DockerClientFactory.instance().isDockerAvailable()) {
    System.out.println("Docker is available");
} else {
    System.err.println("Docker is not accessible");
}

// Get Docker host information
String dockerHost = DockerClientFactory.instance().dockerHostIpAddress();
System.out.println("Docker host: " + dockerHost);

// Get API version
String apiVersion = DockerClientFactory.instance().getActiveApiVersion();
System.out.println("Docker API version: " + apiVersion);

// Check session information
String sessionId = DockerClientFactory.SESSION_ID;
Map<String, String> labels = DockerClientFactory.DEFAULT_LABELS;
System.out.println("Session ID: " + sessionId);
System.out.println("Default labels: " + labels);

/**
 * Utility class for Testcontainers operations.
 * Provides methods for exposing host ports to containers.
 *
 * Uses Lombok @UtilityClass annotation - all methods are static at compile time.
 */
@UtilityClass
public class Testcontainers {
    /**
     * Expose host ports to all containers.
     * Allows containers to access services running on the test host.
     *
     * @param ports ports to expose from the host
     */
    public void exposeHostPorts(int... ports);

    /**
     * Expose host ports with custom port mapping.
     * Map key: port on the host machine
     * Map value: port as visible to containers (can differ from host port)
     *
     * @param ports map where key=host port, value=container-visible port
     */
    public void exposeHostPorts(Map<Integer, Integer> ports);
}

import org.testcontainers.Testcontainers;

// Expose a single port
Testcontainers.exposeHostPorts(8080);

// Expose multiple ports
Testcontainers.exposeHostPorts(8080, 5432, 6379);

// Containers can now access host services at:
// - host.testcontainers.internal:8080
// - host.testcontainers.internal:5432
// - host.testcontainers.internal:6379

// Custom port mapping
Map<Integer, Integer> portMapping = new HashMap<>();
portMapping.put(8080, 9080);  // Host port 8080 → container sees 9080
portMapping.put(5432, 5433);  // Host port 5432 → container sees 5433
Testcontainers.exposeHostPorts(portMapping);

// Example: Test container accessing host service
GenericContainer<?> app = new GenericContainer<>(DockerImageName.parse("myapp:latest"))
    .withEnv("API_URL", "http://host.testcontainers.internal:8080")
    .withExposedPorts(3000);

Testcontainers.exposeHostPorts(8080);
app.start();
// Container can now call back to the test host

/**
 * Strategy for providing Docker client configuration.
 * Implementations detect and configure specific Docker environments.
 *
 * Strategies are automatically discovered via ServiceLoader and selected based on:
 * 1. Priority (higher priority tried first)
 * 2. test() method return value (must return true)
 * 3. First successful strategy is used
 */
public abstract class DockerClientProviderStrategy {
    /**
     * Test if this strategy is viable for the current environment.
     * Called by DockerClientFactory to determine which strategy to use.
     *
     * @return true if this strategy can provide a working Docker client
     */
    public abstract boolean test();

    /**
     * Get the Docker client using this strategy.
     *
     * @return configured Docker client
     */
    public DockerClient getDockerClient();

    /**
     * Get the transport configuration for this strategy.
     *
     * @return transport configuration
     */
    public TransportConfig getTransportConfig();

    /**
     * Get a description of this strategy.
     *
     * @return human-readable description
     */
    public String getDescription();

    /**
     * Get the priority of this strategy.
     * Higher priority strategies are tried first.
     *
     * @return priority value
     */
    public int getPriority();
}

/**
 * Docker Desktop provider strategy.
 * Detects and configures Docker Desktop on macOS and Windows.
 */
public class DockerDesktopClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Unix socket provider strategy.
 * Uses Unix socket for Docker daemon communication (Linux, macOS).
 */
public class UnixSocketClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Windows named pipe provider strategy.
 * Uses named pipes for Docker Desktop on Windows.
 */
public class NpipeSocketClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Docker Machine provider strategy.
 * Connects to Docker Machine environments.
 */
public class DockerMachineClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Environment variable provider strategy.
 * Uses DOCKER_HOST and related environment variables.
 */
public class EnvironmentAndSystemPropertyClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Testcontainers host property provider strategy.
 * Uses testcontainers.properties configuration.
 */
public class TestcontainersHostPropertyClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Rootless Docker provider strategy.
 * Supports rootless Docker installations.
 */
public class RootlessDockerClientProviderStrategy
    extends DockerClientProviderStrategy {
    @Override
    public boolean test();
}

/**
 * Transport configuration for Docker client connections.
 * Contains connection details and transport type.
 *
 * UNSTABLE API - Subject to change without notice.
 * This is an internal configuration class used by provider strategies.
 * Most users don't need to interact with this directly.
 */
@UnstableAPI
public class TransportConfig {
    // Transport-specific configuration methods (internal use)
}

/**
 * Exception thrown when a DockerClientProviderStrategy fails to configure
 * a working Docker client. This typically indicates misconfiguration or
 * unavailable Docker daemon.
 *
 * Common causes:
 * - Docker daemon is not running
 * - Invalid DOCKER_HOST configuration
 * - Incorrect TLS certificate configuration
 * - Network connectivity issues to remote Docker host
 */
public class InvalidConfigurationException extends RuntimeException {
    public InvalidConfigurationException(String message);
    public InvalidConfigurationException(String message, Throwable cause);
}

# Docker host
export DOCKER_HOST=tcp://192.168.99.100:2376

# TLS configuration
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certs

# Docker config location
export DOCKER_CONFIG=/path/to/config

# Docker host configuration
docker.host=tcp://192.168.99.100:2376

# TLS settings
docker.tls.verify=1
docker.cert.path=/path/to/certs

# Testcontainers settings
testcontainers.reuse.enable=false
testcontainers.ryuk.disabled=false

// Check Docker availability before tests
public class DockerConfigurationTest {

    @BeforeAll
    public static void checkDockerAvailability() {
        Assumptions.assumeTrue(
            DockerClientFactory.instance().isDockerAvailable(),
            "Docker is not available - skipping tests"
        );
    }

    @Test
    public void testWithDocker() {
        // Test will only run if Docker is available
        GenericContainer<?> container = new GenericContainer<>(
            DockerImageName.parse("redis:7.0"));
        container.start();
        // ...
    }
}

# TCP connection without TLS
export DOCKER_HOST=tcp://192.168.1.100:2375

# TCP connection with TLS
export DOCKER_HOST=tcp://192.168.1.100:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=$HOME/.docker/certs

# SSH tunnel
export DOCKER_HOST=ssh://user@remote-host

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.DockerClientFactory;
import org.testcontainers.utility.DockerImageName;

// Container will use remote Docker host from DOCKER_HOST
GenericContainer<?> redis = new GenericContainer<>(DockerImageName.parse("redis:7.0"))
    .withExposedPorts(6379);

redis.start();

// Get remote Docker host info
String remoteHost = DockerClientFactory.instance().dockerHostIpAddress();
System.out.println("Connected to Docker host: " + remoteHost);

# Remote Docker host
docker.host=tcp://192.168.1.100:2376

# TLS configuration
docker.tls.verify=1
docker.cert.path=/Users/username/.docker/certs

# Docker context (alternative)
docker.context=remote-context

import org.testcontainers.DockerClientFactory;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.utility.DockerImageName;

// Get remote Docker Unix socket path
String socketPath = DockerClientFactory.instance().getRemoteDockerUnixSocketPath();
System.out.println("Remote socket: " + socketPath);

// Mount Docker socket for Docker-in-Docker
GenericContainer<?> dind = new GenericContainer<>(DockerImageName.parse("docker:dind"))
    .withPrivilegedMode(true)
    .withFileSystemBind(socketPath, "/var/run/docker.sock")
    .withExposedPorts(2375);

dind.start();

# Create Docker context for remote host
docker context create remote --docker "host=tcp://192.168.1.100:2376,ca=/path/to/ca.pem,cert=/path/to/cert.pem,key=/path/to/key.pem"

# Use context
docker context use remote

# Testcontainers will automatically use active context

# SSH tunnel configuration
export DOCKER_HOST=ssh://user@remote-docker-host

# With custom SSH identity file
export DOCKER_HOST=ssh://user@remote-docker-host
export DOCKER_SSH_OPTS="-i /path/to/ssh-key"

// Testcontainers automatically uses SSH tunnel
GenericContainer<?> postgres = new GenericContainer<>(DockerImageName.parse("postgres:15"))
    .withExposedPorts(5432)
    .withEnv("POSTGRES_PASSWORD", "test");

postgres.start();

// Access container on remote host
String jdbcUrl = String.format(
    "jdbc:postgresql://%s:%d/postgres",
    postgres.getHost(),
    postgres.getMappedPort(5432)
);

~/.docker/certs/
├── ca.pem          # Certificate Authority
├── cert.pem        # Client certificate
└── key.pem         # Private key

export DOCKER_HOST=tcp://remote-docker-host:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=$HOME/.docker/certs

# ~/.testcontainers.properties
docker.host=tcp://remote-docker-host:2376
docker.tls.verify=1
docker.cert.path=/Users/username/.docker/certs

import org.testcontainers.containers.GenericContainer;
import org.testcontainers.DockerClientFactory;
import org.testcontainers.utility.DockerImageName;

// Docker-in-Docker container
GenericContainer<?> dind = new GenericContainer<>(DockerImageName.parse("docker:24-dind"))
    .withPrivilegedMode(true)  // Required for DinD
    .withExposedPorts(2375, 2376)
    .withEnv("DOCKER_TLS_CERTDIR", "");  // Disable TLS for simplicity

dind.start();

// Get DinD Docker host
String dindHost = String.format(
    "tcp://%s:%d",
    dind.getHost(),
    dind.getMappedPort(2375)
);

// Configure Testcontainers to use DinD
System.setProperty("DOCKER_HOST", dindHost);

// Now containers will run inside DinD
GenericContainer<?> nested = new GenericContainer<>(DockerImageName.parse("redis:7.0"))
    .withExposedPorts(6379);

nested.start();

# Create Docker Machine
docker-machine create --driver virtualbox testcontainers-machine

# Get environment variables
docker-machine env testcontainers-machine

# Export Docker Machine environment
eval $(docker-machine env testcontainers-machine)

# Testcontainers will use Docker Machine

import org.testcontainers.DockerClientFactory;
import org.testcontainers.dockerclient.DockerMachineClientProviderStrategy;

// Check if using Docker Machine
boolean usingDockerMachine = DockerClientFactory.instance()
    .isUsing(DockerMachineClientProviderStrategy.class);

if (usingDockerMachine) {
    System.out.println("Using Docker Machine for Docker host");
}

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      docker:
        image: docker:dind
        options: --privileged
    env:
      DOCKER_HOST: tcp://docker:2375
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: mvn test

test:
  image: maven:3.8-openjdk-11
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  script:
    - mvn test

pipeline {
    agent any
    environment {
        DOCKER_HOST = 'tcp://remote-docker-host:2376'
        DOCKER_TLS_VERIFY = '1'
        DOCKER_CERT_PATH = credentials('docker-tls-certs')
    }
    stages {
        stage('Test') {
            steps {
                sh 'mvn test'
            }
        }
    }
}

// Container runs on remote host
GenericContainer<?> app = new GenericContainer<>(DockerImageName.parse("myapp:latest"))
    .withExposedPorts(8080);

app.start();

// getHost() returns remote Docker host IP
String host = app.getHost();  // e.g., "192.168.1.100"
Integer port = app.getMappedPort(8080);  // e.g., 32768

// Access application on remote host
String url = String.format("http://%s:%d", host, port);

// Debug remote Docker connection
DockerClientFactory factory = DockerClientFactory.instance();

if (!factory.isDockerAvailable()) {
    System.err.println("Cannot connect to Docker!");
    System.err.println("Ensure DOCKER_HOST is set correctly");
    System.err.println("Verify Docker daemon is running on remote host");
    System.err.println("Check firewall allows connections to Docker port (usually 2375/2376)");
}

// Test Docker connection
try {
    DockerClient client = factory.client();
    com.github.dockerjava.api.model.Info info = client.infoCmd().exec();
    System.out.println("Connected to Docker daemon: " + info.getName());
    System.out.println("Server version: " + info.getServerVersion());
} catch (Exception e) {
    System.err.println("Docker connection failed: " + e.getMessage());
}

# Verify certificates are readable
ls -la ~/.docker/certs/
# Should contain: ca.pem, cert.pem, key.pem

# Test Docker connection manually
docker --tlsverify \
    --tlscacert=~/.docker/certs/ca.pem \
    --tlscert=~/.docker/certs/cert.pem \
    --tlskey=~/.docker/certs/key.pem \
    -H=tcp://remote-host:2376 ps

import org.testcontainers.DockerClientFactory;
import com.github.dockerjava.api.DockerClient;
import com.github.dockerjava.api.command.InspectImageResponse;

public class CustomDockerClientExample {

    @Test
    public void testWithCustomClient() {
        DockerClient client = DockerClientFactory.instance().client();

        // Use Docker client directly for advanced operations
        InspectImageResponse imageInfo = client
            .inspectImageCmd("postgres:15")
            .exec();

        System.out.println("Image ID: " + imageInfo.getId());
        System.out.println("Created: " + imageInfo.getCreated());

        // List all Testcontainers resources
        client.listContainersCmd()
            .withShowAll(true)
            .withLabelFilter(Map.of(
                DockerClientFactory.TESTCONTAINERS_LABEL, "true"
            ))
            .exec()
            .forEach(container -> {
                System.out.println("Container: " + container.getId());
                System.out.println("Names: " + Arrays.toString(container.getNames()));
            });
    }
}

import org.testcontainers.utility.ResourceReaper;

/**
 * ResourceReaper singleton manages cleanup of Docker resources.
 * All methods are deprecated - resource cleanup is handled automatically by Testcontainers.
 */
public class ResourceReaper {
    /**
     * Get the singleton instance.
     *
     * @return ResourceReaper instance
     */
    public static ResourceReaper instance();

    /**
     * Get the labels used for resource tracking.
     *
     * @return map of labels applied to resources managed by ResourceReaper
     */
    public Map<String, String> getLabels();

    /**
     * Register a container for cleanup at JVM shutdown.
     *
     * @param containerId container ID
     * @param imageName image name
     * @deprecated Resource cleanup is handled automatically by Testcontainers
     */
    @Deprecated
    public void registerContainerForCleanup(String containerId, String imageName);

    /**
     * Register a network for cleanup.
     *
     * @param networkId network ID
     * @deprecated Resource cleanup is handled automatically by Testcontainers
     */
    @Deprecated
    public void registerNetworkIdForCleanup(String networkId);

    /**
     * Register an image for cleanup.
     *
     * @param imageName image name
     * @deprecated Resource cleanup is handled automatically by Testcontainers
     */
    @Deprecated
    public void registerImageForCleanup(String imageName);

    /**
     * Stop and remove a container.
     *
     * @param containerId container ID
     * @deprecated Resource cleanup is handled automatically by Testcontainers
     */
    @Deprecated
    public void stopAndRemoveContainer(String containerId);

    /**
     * Remove a network.
     *
     * @param networkId network ID
     * @deprecated Resource cleanup is handled automatically by Testcontainers
     */
    @Deprecated
    public void removeNetworkById(String networkId);
}

// Disable Ryuk (resource reaper) for debugging
// In testcontainers.properties:
// testcontainers.ryuk.disabled=true

// Or via environment variable:
System.setProperty("testcontainers.ryuk.disabled", "true");

// Manual cleanup when Ryuk is disabled
ResourceReaper reaper = ResourceReaper.instance();
String containerId = container.getContainerId();
reaper.stopAndRemoveContainer(containerId);

import org.testcontainers.Testcontainers;
import org.testcontainers.containers.GenericContainer;

public class HostAccessExample {

    @Test
    public void testContainerAccessingHostService() {
        // Start a local service on the host
        int hostPort = 8080;
        LocalService service = new LocalService(hostPort);
        service.start();

        try {
            // Expose host port to containers
            Testcontainers.exposeHostPorts(hostPort);

            // Container can access host service
            GenericContainer<?> client = new GenericContainer<>(
                    DockerImageName.parse("appropriate/curl:latest"))
                .withCommand(
                    "sh", "-c",
                    "curl http://host.testcontainers.internal:" + hostPort + "/health"
                );

            client.start();

            // Wait for completion
            Thread.sleep(2000);

            // Check logs
            String logs = client.getLogs();
            assertTrue(logs.contains("OK"), "Container should reach host service");

        } finally {
            service.stop();
        }
    }
}

import org.testcontainers.DockerClientFactory;
import com.github.dockerjava.api.DockerClient;
import com.github.dockerjava.api.model.Info;
import com.github.dockerjava.api.model.Version;

public class DockerInfoExample {

    @Test
    public void printDockerInformation() {
        DockerClient client = DockerClientFactory.instance().client();

        // Get Docker version
        Version version = client.versionCmd().exec();
        System.out.println("Docker version: " + version.getVersion());
        System.out.println("API version: " + version.getApiVersion());
        System.out.println("OS/Arch: " + version.getOperatingSystem() + "/" + version.getArch());

        // Get Docker daemon info
        Info info = client.infoCmd().exec();
        System.out.println("Containers: " + info.getContainers());
        System.out.println("Images: " + info.getImages());
        System.out.println("Driver: " + info.getDriver());
        System.out.println("Total Memory: " + info.getMemTotal());
        System.out.println("Operating System: " + info.getOperatingSystem());

        // Get host IP
        String dockerHost = DockerClientFactory.instance().dockerHostIpAddress();
        System.out.println("Docker host IP: " + dockerHost);
    }
}

import org.testcontainers.DockerClientFactory;
import org.testcontainers.utility.TestcontainersConfiguration;

public class DockerConnectionDebug {

    @Test
    public void debugDockerConnection() {
        // Check if Docker is available
        boolean available = DockerClientFactory.instance().isDockerAvailable();
        System.out.println("Docker available: " + available);

        if (!available) {
            System.err.println("Docker is not available!");
            System.err.println("Checked strategies:");
            // Strategies are tried in order until one succeeds
            return;
        }

        // Get configuration
        TestcontainersConfiguration config = TestcontainersConfiguration.getInstance();
        System.out.println("Configuration properties:");
        config.getProperties().forEach((key, value) -> {
            System.out.println("  " + key + " = " + value);
        });

        // Get API version
        String apiVersion = DockerClientFactory.instance().getActiveApiVersion();
        System.out.println("API version: " + apiVersion);
    }
}

// Solution: Verify Docker is running
if (!DockerClientFactory.instance().isDockerAvailable()) {
    throw new IllegalStateException(
        "Docker is not available. Please start Docker daemon."
    );
}

# Linux: Add user to docker group
sudo usermod -aG docker $USER
# Logout and login again

# Set DOCKER_HOST environment variable
export DOCKER_HOST=tcp://remote-docker-host:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certs

# In ~/.testcontainers.properties
docker.host=unix:///var/run/docker.sock
# Or for remote Docker:
docker.host=tcp://192.168.99.100:2376
docker.tls.verify=1
docker.cert.path=/path/to/certs