CI and Docker Environments

## The problem this solves Testcontainers is a client of the Docker Engine API. It does not embed a container runtime; it asks *some* daemon to pull images and start containers. On a developer laptop that daemon is usually Docker Desktop or Colima. On a CI runner it might be a socket bind-mounted into a job container, a `docker:dind` service reachable over TCP, a rootless daemon in a user session, or a remote managed worker. Because the location varies so much, Testcontainers resolves the daemon at runtime instead of hardcoding a path. ## The strategy chain Resolution is implemented as an ordered set of `DockerClientProviderStrategy` implementations. Each one is asked to produce a client configuration; the library then pings the resulting endpoint, and the first strategy whose ping succeeds is cached for the whole JVM. The strategies that matter in practice are: - **Testcontainers host property** — the `tc.host` entry in `~/.testcontainers.properties`, equivalently the `TESTCONTAINERS_HOST_OVERRIDE` environment variable. This is the explicit "talk to this daemon" escape hatch. - **Environment and system property** — the standard Docker client variables `DOCKER_HOST`, `DOCKER_TLS_VERIFY` and `DOCKER_CERT_PATH`, read from the environment or from equivalent JVM system properties. This is how every `docker:dind` and remote-daemon setup is wired. - **Unix socket** — a direct connection to `/var/run/docker.sock`. This is what a socket-mounted CI job container hits. - **Docker Desktop and rootless strategies** — the per-user socket paths those installations create; on Windows the named-pipe strategy plays the same role. If you already know which one applies, set the `docker.client.strategy` property to that strategy's class name. That skips the probing entirely, which removes both a few seconds of startup and a class of confusing "it picked the wrong daemon" bugs on machines that have two. ## Where configuration comes from Three inputs feed the chain, in a consistent shape. Entries in `~/.testcontainers.properties` (for example `docker.client.strategy`, `tc.host`, `checks.disable`) are the file form. The same settings exist as environment variables with a `TESTCONTAINERS_` prefix and dots replaced by underscores — `TESTCONTAINERS_RYUK_DISABLED`, `TESTCONTAINERS_CHECKS_DISABLE`, `TESTCONTAINERS_HOST_OVERRIDE`. And the plain Docker variables (`DOCKER_HOST` and friends) are honoured because they are what every other Docker tool already reads. On CI, environment variables are almost always the right form: they are set per job, they need no filesystem provisioning on an ephemeral runner, and they are what the runner image documents. ## Startup checks Before the first container, Testcontainers runs a couple of environment sanity checks against the daemon it found. They cost a second or two and catch a broken environment early. On a fleet of identical runners where the environment is known good, `TESTCONTAINERS_CHECKS_DISABLE=true` removes them. Treat it as a speed knob, not a fix — if the checks fail, the environment is genuinely wrong. ## Registry credentials Finding the daemon is only half of a successful start; the daemon must also be able to pull the image. Testcontainers reads the Docker CLI's own credential store — `~/.docker/config.json`, or the directory named by `DOCKER_CONFIG` — including credential helper entries, and passes the matching auth to the pull. On CI this means an ordinary `docker login` step (or the equivalent registry-login action) earlier in the job is enough; you do not configure credentials in test code. Anonymous pulls from a public hub are rate limited, so authenticated pulls or an internal mirror are the usual production answer for a busy pipeline. ## Diagnosing failures The symptom of a bad environment is a fast, loud failure at the first container start: an exception whose message is "Could not find a valid Docker environment". Read it as "no strategy pinged successfully" and check, in order: is a daemon running at all on this runner; is `DOCKER_HOST` set and reachable; if using the socket, is `/var/run/docker.sock` actually mounted into the job container and readable by the job's user. A user without permission on the socket produces a permission error rather than a missing-daemon error, which is a useful discriminator. None of these are test bugs, and none of them are fixed in test code — they are runner configuration.