Docker-in-Docker considerations in Jenkins - Commands & Configuration

Introduction

Running Docker inside a Docker container helps build and test container images in isolated environments. It solves the problem of needing Docker commands inside CI/CD pipelines without installing Docker on the host directly.

When you want to build Docker images inside a Jenkins pipeline running in a container.

When you need to run integration tests that require Docker containers inside a CI job.

When you want to isolate Docker environments for different builds to avoid conflicts.

When your Jenkins agents do not have Docker installed but you still want to use Docker commands.

When you want to speed up builds by caching Docker layers inside containers.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent {
    docker {
      image 'docker:24.0.5'
      args '--privileged -v /var/run/docker.sock:/var/run/docker.sock'
    }
  }
  stages {
    stage('Build Docker Image') {
      steps {
        sh 'docker build -t my-app-image .'
      }
    }
  }
}

This Jenkinsfile defines a pipeline that runs inside a Docker container using the official Docker image version 24.0.5.

The --privileged flag allows the container to run Docker daemon commands.

The volume mount -v /var/run/docker.sock:/var/run/docker.sock shares the host's Docker socket, enabling Docker commands inside the container to communicate with the host Docker daemon.

This setup avoids running a full Docker daemon inside the container, which is complex and less efficient.

Commands

This command runs a Docker container named 'jenkins-agent' with privileged mode and mounts the host Docker socket. It simulates the Jenkins agent environment that can run Docker commands inside the container.

Terminal

docker run --privileged -d -v /var/run/docker.sock:/var/run/docker.sock --name jenkins-agent docker:24.0.5 sleep infinity

Expected Output

a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef0

→

--privileged - Allows the container to run Docker commands that require extended privileges.

→

-v /var/run/docker.sock:/var/run/docker.sock - Shares the host Docker socket with the container to use the host Docker daemon.

→

-d - Runs the container in detached mode.

Runs the 'docker ps' command inside the 'jenkins-agent' container to list running containers using the host Docker daemon.

Terminal

docker exec jenkins-agent docker ps

Expected Output

CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS     NAMES

Builds a Docker image named 'my-app-image' inside the 'jenkins-agent' container using the host Docker daemon.

Terminal

docker exec jenkins-agent docker build -t my-app-image .

Expected Output

Sending build context to Docker daemon  2.048kB

Step 1/2 : FROM alpine:3.18

3.18: Pulling from library/alpine

Digest: sha256:...

Status: Downloaded newer image for alpine:3.18

 ---> abcdef123456

Step 2/2 : CMD ["echo", "Hello from my-app-image"]

 ---> Running in 123456abcdef

Removing intermediate container 123456abcdef

Successfully built 7890abcdef12

Successfully tagged my-app-image:latest

Runs the 'my-app-image' Docker image inside the 'jenkins-agent' container to verify the image was built correctly.

Terminal

docker exec jenkins-agent docker run --rm my-app-image

Expected Output

Hello from my-app-image

→

--rm - Automatically removes the container after it exits.

Key Concept

If you remember nothing else from Docker-in-Docker, remember: mounting the host Docker socket inside a privileged container lets you run Docker commands inside containers without running a full Docker daemon inside them.

Common Mistakes

Running Docker-in-Docker without the --privileged flag

Docker commands inside the container fail due to insufficient permissions.

Always add the --privileged flag when running containers that need to execute Docker commands.

Not mounting the Docker socket from the host

Docker commands inside the container cannot communicate with the Docker daemon, causing failures.

Mount /var/run/docker.sock from the host into the container to share the Docker daemon.

Trying to run a full Docker daemon inside the container without mounting the socket

Running a Docker daemon inside a container is complex, slow, and error-prone.

Use the host Docker daemon by mounting the socket instead of running a daemon inside the container.

Summary

Run Jenkins agents in Docker containers with --privileged and mount the host Docker socket to enable Docker commands inside containers.

Use the official Docker image as the Jenkins agent environment to have Docker CLI tools available.

Verify Docker commands inside the container by running 'docker ps', building images, and running containers using the host Docker daemon.