Docker-in-Docker

~9 min · docker, dind, isolation

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Building containers from inside a container

Hosted runners ship with Docker preinstalled. On self-hosted, especially when you containerize the runner itself, you need a strategy for running Docker commands inside the runner.

Three patterns

Mount the host Docker socket — /var/run/docker.sock into the runner. Easiest. Insecure: a job can break out to the host.
Docker-in-Docker (dind) — run a separate Docker daemon inside the runner. Safer; slower; needs --privileged or rootless dind.
Buildkit standalone — for image builds only, Buildkit can run without dockerd. Slim and fast.

Recommendation

For trusted code: socket mount is fine, easy, and fast.
For untrusted code: rootless dind or Kaniko/Buildkit.
For Apple Silicon: Docker Desktop on the Mac handles the daemon; runner agent talks to it normally.

Code

Runner with mounted Docker socket·yaml

# docker-compose.yml for self-hosted runner
services:
  runner:
    image: ghcr.io/myorg/runner:latest
    environment:
      RUNNER_TOKEN: ${RUNNER_TOKEN}
      RUNNER_REPOSITORY_URL: https://github.com/my-org/my-repo
      RUNNER_LABELS: self-hosted,linux-x64,docker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - runner-cache:/home/runner
    restart: unless-stopped

volumes:
  runner-cache:

External links

Exercise

If your self-hosted runner builds Docker images, classify how it does Docker today: socket mount, dind, Buildkit, or something else. Match it to the trust tier of code it runs. Migrate if needed.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousmacOS Runners (and Apple Silicon)Next →Act — Local Workflow Testing

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.