Skip to content
Tutorials Center
My learning

Topics

Lesson 96 of 111 ยท Orchestration Basics

Docker in Docker and Socket Access

How to run docker commands from inside a container: Docker-in-Docker, mounting the socket, remote daemons, rootless builders and Testcontainers, with their risks.

Sooner or later you will meet a task that sounds simple: "run docker build or docker run from inside a container." A CI job that runs in a container wants to build an image. A test suite wants to start a real database in a throwaway container. A dashboard wants to list the containers on its host. All three need access to a Docker daemon from a place that is itself a container.

There are several ways to do it, and they are very different in safety. This lesson explains the three classic patterns (Docker-out-of-Docker with the socket, true Docker-in-Docker, and a remote daemon), what each one costs, what to use for CI builds and for Testcontainers, and which safer options exist. Because the shared daemon used to verify this track must not be exposed to risky setups, the privileged and socket-mounting examples are read-only; the parts that could be run safely were run, and their output is real.

Everything here circles around one fact from Securing the Docker Daemon: access to a Docker daemon is equivalent to root on the machine that runs it. A container with that access is not a sandbox any more. Read that lesson first if you have not.

The Docker client is just a client

Remember the architecture from How Docker Works: docker is a small program that sends API requests to a daemon. To use Docker from inside a container you need two things: the client binary in the container, and a way to reach a daemon. The official docker:cli image provides the first; it contains the CLI, Buildx and Compose, but no daemon:

CONSOLE
$ docker run --rm docker:cli docker --version
Docker version 29.9.2, build a82e528
$ docker run --rm docker:cli sh -c 'docker buildx version; docker compose version'
github.com/docker/buildx v0.38.1 0dbe87f36ed472fe36b6796c3f70b4210a731fc5
Docker Compose version v5.6.1

(Versions are those of the image when this lesson was verified. The image is about 240 MB on disk.) With no daemon to talk to, the client fails in a recognizable way:

CONSOLE
$ docker run --rm docker:cli docker version
Client:
 Version:           29.9.2
 API version:       1.56
 Go version:        go1.26.10
 Git commit:        a82e528
 Built:             Tue Oct 20 18:44:02 2026
 OS/Arch:           linux/amd64
 Context:           default
failed to connect to the docker API at tcp://docker:2375: lookup docker on 192.168.65.7:53: no such host

Look at the address: tcp://docker:2375. The image's entrypoint script sets DOCKER_HOST to a host named docker when there is no socket mounted. That default exists for the Docker-in-Docker pattern below, where a sidecar container with the network alias docker is the daemon. You can also point the client anywhere yourself:

CONSOLE
$ docker run --rm -e DOCKER_HOST=tcp://127.0.0.1:2375 docker:cli docker ps
Cannot connect to the Docker daemon at tcp://127.0.0.1:2375. Is the docker daemon running?

Everything below is a different answer to the question: which daemon should the client reach?

Pattern 1: Docker-out-of-Docker (mount the socket)

The simplest answer is to give the container the host's daemon by mounting its socket:

Terminal
# READ-ONLY EXAMPLE - understand the risk before running anything like this
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker:cli docker ps

Inside, docker ps lists the host's containers, and docker run starts containers on the host. These are not nested: they are siblings of the container that asked for them. This pattern is often called Docker-out-of-Docker (DooD).

TEXT
 host
 +-- dockerd  <------------------------------+
 |     |  creates                             | /var/run/docker.sock
 |     +--> [ CI job container ] -------------+  (mounted)
 |     +--> [ test database ]   <- created by the job, but a sibling
 |     +--> [ other app containers ]

Advantages: it is fast, because it shares the host's image cache and no second daemon runs; it needs no --privileged; images built inside are available on the host at once. The downsides are serious:

  • Root on the host. The job can start docker run -v /:/host ... and own the machine. If the job runs untrusted code (a pull request from a stranger), you have given that stranger root.
  • No isolation between jobs. Jobs see each other's containers, volumes and networks and can stop or delete them. Leftovers pile up.
  • Path confusion. -v "$PWD:/app" in a job refers to a path on the host, not in the job container, because the daemon resolves paths. If the job's working directory is not on the host, the mount is empty or wrong. This is the most common bug in this pattern.
  • Naming and port clashes. A fixed container name or published port in one job collides with another job on the same host.

Mounting the socket read-only (:ro) does not reduce any of this, as explained in Securing the Docker Daemon.

Pattern 2: Docker-in-Docker (a daemon inside a container)

The docker:dind image runs a complete Docker daemon inside a container. Your job talks to this inner daemon over TCP, so the containers it creates live inside the dind container and vanish with it. Nothing touches the host's daemon.

The catch: a daemon needs to create namespaces, mount filesystems and manage cgroups, so the dind container must run with --privileged. That removes almost all of the container isolation between the dind container and the host. Compose makes the topology readable. This is a read-only example; it was checked with docker compose config -q but, because it needs a privileged container, it was not started on the shared daemon:

YAML
services:
  docker:
    image: docker:dind
    privileged: true
    environment:
      DOCKER_TLS_CERTDIR: /certs
    volumes:
      - certs-ca:/certs/ca
      - certs-client:/certs/client
  tests:
    image: docker:cli
    depends_on:
      - docker
    environment:
      DOCKER_HOST: tcp://docker:2376
      DOCKER_TLS_VERIFY: "1"
      DOCKER_CERT_PATH: /certs/client
    volumes:
      - certs-client:/certs/client:ro
    command: ["docker", "version"]
volumes:
  certs-ca:
  certs-client:

Walk through it:

  1. The service is called docker, so other containers on the Compose network reach it as tcp://docker:2376. That is the name the docker:cli entrypoint expects.
  2. DOCKER_TLS_CERTDIR=/certs makes the inner daemon generate a CA and certificates and listen on the TLS port 2376. Without it, the daemon listens on plain port 2375, so anyone on the network gets root in the dind container. Always keep TLS on.
  3. The certs-client volume carries the client certificate to the tests container, which uses DOCKER_TLS_VERIFY and DOCKER_CERT_PATH to present it.

The result for the test container is a clean, empty daemon. What it builds or pulls is stored inside the dind container (or a volume you attach to /var/lib/docker).

Advantages: clean state per job, no clashes with other jobs, the host's containers are invisible. Disadvantages:

  • privileged: true. A compromise of the dind container is a compromise of the host. DinD protects your containers from each other far better than it protects the host. Run it on disposable CI machines, not on a server that hosts your applications.
  • No shared cache. Every fresh dind starts with an empty image cache, so every job pulls base images again and rebuilds from scratch. Persist /var/lib/docker in a volume, or use a registry cache (see Build Performance).
  • Storage driver trouble. An inner overlay2 on top of the host's overlay2 can fail on some kernels and filesystems. You may need --storage-driver=vfs, which is slow and space hungry.
  • Cleanup. Stopping the dind container does not remove its volumes unless you ask.

DinD exists mostly because of CI systems: the GitLab runner's docker executor and many hosted CI services provide it as a "service container". It is also what the Docker project itself used to test Docker.

Pattern 3: A remote or separate daemon

A third answer is to point the client at a daemon on another machine: a dedicated build host. The job container has no privileges at all and only holds a client certificate or an SSH key:

Terminal
# READ-ONLY EXAMPLE
docker context create ci-builder --docker "host=ssh://[email protected]"
docker --context ci-builder build -t myorg/app:1.4.2 .

The build runs on builder.example.com, which is a machine dedicated to this purpose and can be wiped regularly. The contexts and TLS setup are explained in Securing the Docker Daemon. Many teams use hosted remote builders for the same effect. Compare it to DinD: you pay for a separate machine, but the privileged piece is isolated from everything else.

Safer ways to build images in CI

If all you need is to build images, you do not need a Docker daemon at all. Tools designed for CI avoid both the socket and the privileged container:

  • BuildKit (the engine behind docker build) can run as a rootless daemon or as a one-shot buildctl job in a container with reduced privileges.
  • Kaniko, Buildah and img build from a Dockerfile in user space and push to a registry, with no daemon.
  • Buildx with a remote or Kubernetes builder sends the build to a long-running BuildKit service that is isolated from your jobs (see BuildKit and buildx).
  • Hosted build services (a cloud build product, or your registry vendor's builders) remove the question: you submit the build context, you get an image.

For the shape of a real pipeline, see Docker in CI. A good default: build with a rootless or remote builder, push to a registry, deploy from the registry. Keep docker run on the host out of the CI job.

Testcontainers and tests that need real services

Many projects want integration tests against real PostgreSQL or Redis rather than mocks. The Testcontainers libraries (for Java, Go, .NET, Node.js, Python, Rust and more) do this: the test code starts a container through the Docker API, waits for it to be ready, connects, and removes it after the test. A read-only example in Java:

Java
@Testcontainers
class OrderRepositoryTest {

    @Container
    static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:17-alpine");

    @Test
    void savesAnOrder() throws Exception {
        try (var connection = DriverManager.getConnection(
                db.getJdbcUrl(), db.getUsername(), db.getPassword())) {
            // run schema, insert, query ...
        }
    }
}

The library needs a daemon. On your laptop that is Docker Desktop, so nothing special is required. In CI you have the choices above:

  1. Run the tests directly on a CI machine that has Docker (a VM runner). The VM is thrown away after the job, which makes socket access acceptable.
  2. Use a remote daemon, with DOCKER_HOST set; Testcontainers respects it, and some vendors offer a hosted version of the service that avoids a local daemon.
  3. Use DinD if the CI system is container-based. Remember that Testcontainers publishes ports on the Docker host, which in DinD is the docker service, not localhost. Set TESTCONTAINERS_HOST_OVERRIDE=docker if connections fail.
  4. Mount the socket only on trusted, disposable runners, never on shared infrastructure that runs untrusted pull requests.

Testcontainers starts a helper container called "Ryuk" that deletes leftovers when the tests end, so a crash does not leave databases running. Containers it creates are siblings, not children, which is the DooD behavior from above. Use ready checks (a log message or a port) rather than fixed sleeps, and pin image tags, so the tests are reproducible.

Choosing between the patterns

Need Best choice Why
Build and push images in CI Rootless BuildKit, Kaniko or a remote builder No socket and no privileged container
Integration tests with Testcontainers A disposable VM runner with Docker Isolation comes from the VM
Container-based CI needing a daemon DinD with TLS, on throwaway machines Clean per-job state; accept privileged
Quick local experiments on your own machine Socket mount Convenient; you are the only user
Show or manage containers (dashboards) A read-only socket proxy, or no socket Limits the API calls to a small safe set
Deploy from CI to a server Registry plus SSH or an orchestrator API The job never needs a daemon

If in doubt, ask: who writes the code that runs in this container, and what would they gain with root on the host? If the answer is "anyone, and everything", do not use sockets or privileged containers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A job container with the host's /var/run/docker.sock mounted runs docker run postgres. Where does the postgres container run?

    The socket gives the job access to the host's daemon, which creates the container next to the job container. Nothing is nested.
  2. 2. Why does a docker:dind container need to run with privileged: true?

    A full daemon needs capabilities that normal containers do not have, so the dind container is privileged, which weakens isolation from the host.
  3. 3. In the Compose example, why is the daemon service named docker?

    On the Compose network the service name resolves to the daemon container, which is where the CLI image looks by default.
  4. 4. A job in Docker-out-of-Docker runs docker run -v "$PWD:/app" myimage. What path does $PWD refer to when the daemon creates the container?

    The daemon resolves bind-mount paths on its own filesystem, which is the host's. A path that exists only in the job container leads to empty or wrong mounts.
  5. 5. You only need to build and push images in CI. Which approach avoids both the socket mount and a privileged container?

    These tools build from a Dockerfile in user space and push to a registry, so no daemon with root power is exposed to the job.

Summary

  • The docker command is only a client; running it in a container requires reaching some daemon. The docker:cli image holds the client, Buildx and Compose but no daemon, and defaults DOCKER_HOST to tcp://docker:2375 (or 2376 with TLS).
  • Mounting the host socket (Docker-out-of-Docker) is fast but gives root on the host, no job isolation and confusing bind-mount paths; created containers are siblings.
  • Docker-in-Docker runs a full daemon in a privileged container, gives clean per-job state but no shared cache; always keep TLS on (DOCKER_TLS_CERTDIR) and use it on throwaway machines.
  • A remote or dedicated build daemon, reached over SSH or TLS, keeps the privileged part away from your jobs.
  • To only build images, prefer rootless BuildKit, Kaniko, Buildah or hosted builders.
  • Testcontainers needs a daemon: use a disposable VM runner, a remote daemon or DinD, and set the host override when containers are not on localhost.

Next: Dev Containers and Remote Development