> ## Documentation Index
> Fetch the complete documentation index at: https://buildcharts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TestcontainersDinD@v1

> Provide an isolated Docker daemon for Testcontainers-based builds.

This plugin provisions a dedicated Docker-in-Docker (DinD) daemon and configures Testcontainers to connect to it during build time, providing an isolated Docker engine.

## Usage

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
plugins:
  - TestcontainersDinD@v1
```

When running `buildcharts generate`, the plugin starts or reuses the DinD container, updates `.buildcharts/docker-bake.hcl`, and leaves the Docker daemon running for reuse (memory footprint \~40 MB).

## What it does

* Starts a `buildcharts-dind` container using the `docker:27-dind` image
* Reuses the container if it already exists, or removes and recreates it if the image differs
* Runs the container in privileged mode, binds port `2375`, and disables TLS
* Supports `BUILDCHARTS_DIND_IMAGE` to override the Docker image tag
* Supports `BUILDCHARTS_DIND_VOLUME=true` to mount the named `buildcharts-dind` volume at `/var/lib/docker`
* Patches the generated `.buildcharts/docker-bake.hcl` for `target "test"`:
  * `TESTCONTAINERS_HOST_OVERRIDE` - arg with DinD container IP
  * `host.docker.internal` - extra host that resolves to the host gateway
* Writes `.buildcharts/plugins/TestcontainersDinD@v1/container_debuginfo.json`

## Environment variables

* `BUILDCHARTS_DIND_IMAGE`
* `BUILDCHARTS_DIND_VOLUME`

## Notes

* If the generated Bake plan has no `test` target, the patch step is skipped.
* The plugin leaves the `buildcharts-dind` container running for reuse across builds.
* Set `BUILDCHARTS_DIND_VOLUME=true` before the first plugin run when you want Docker images inside DinD to persist between runs. If the container already exists, remove it before changing this mode.

## Read more

* [GitHub - docker/buildx - Provide option to allow access to /var/run/docker.sock during build #1991](https://github.com/docker/buildx/issues/1991)
* [Patterns for running tests inside a Docker container](https://java.testcontainers.org/supported_docker_environment/continuous_integration/dind_patterns/)