Docker socket mounting in Jenkins - Commands & Configuration

Introduction

Sometimes, you want a program inside a container to control Docker on the host machine. Docker socket mounting lets the container talk directly to the host's Docker engine. This helps run or manage containers from inside another container.

When Jenkins runs inside a container and needs to build or run Docker containers on the host.

When you want to use Docker commands inside a container without installing Docker inside it.

When automating container builds and deployments from a CI/CD pipeline running in a container.

When you want to share the host Docker daemon with multiple containers safely.

When debugging or managing Docker containers from inside a container environment.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
    agent {
        docker {
            image 'docker:20.10.16'
            args '-v /var/run/docker.sock:/var/run/docker.sock'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'docker ps'
            }
        }
    }
}

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

The args option mounts the host's Docker socket /var/run/docker.sock into the container at the same path. This allows Docker commands inside the container to communicate with the host's Docker daemon.

The Build stage runs docker ps to list running containers on the host, demonstrating access to the host Docker engine.

Commands

This command runs a Jenkins container named 'jenkins-docker'. It mounts the host Docker socket inside the container so Jenkins can control Docker on the host. It also mounts a volume for Jenkins data and exposes port 8080.

Terminal

docker run -d --name jenkins-docker -v /var/run/docker.sock:/var/run/docker.sock -v jenkins_home:/var/jenkins_home -p 8080:8080 jenkins/jenkins:lts

Expected Output

Unable to find image 'jenkins/jenkins:lts' locally

lts: Pulling from jenkins/jenkins

Digest: sha256:...

Status: Downloaded newer image for jenkins/jenkins:lts

c3f279d17e0a4e3a9a1f9b7a2e6f3b7a8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3l

→

-v /var/run/docker.sock:/var/run/docker.sock - Mount host Docker socket inside container

→

-v jenkins_home:/var/jenkins_home - Persist Jenkins data

→

-p 8080:8080 - Expose Jenkins web interface

Runs 'docker ps' inside the Jenkins container to list running Docker containers on the host. This shows that the container can control the host Docker daemon via the mounted socket.

Terminal

docker exec jenkins-docker docker ps

Expected Output

CONTAINER ID   IMAGE                  COMMAND                  CREATED          STATUS          PORTS                    NAMES

c3f279d17e0a4   jenkins/jenkins:lts    "/sbin/tini -- /usr/…"   10 seconds ago   Up 9 seconds    0.0.0.0:8080->8080/tcp   jenkins-docker

Runs a test Docker container 'hello-world' from inside the Jenkins container. This confirms the container can start new containers on the host using the mounted Docker socket.

Terminal

docker exec jenkins-docker docker run --rm hello-world

Expected Output

Unable to find image 'hello-world:latest' locally

latest: Pulling from library/hello-world

Digest: sha256:...

Status: Downloaded newer image for hello-world:latest

Hello from Docker!

This message shows that your installation appears to be working correctly.

Key Concept

Mounting the host's Docker socket inside a container lets that container control Docker on the host directly.

Common Mistakes

Not mounting the Docker socket when running the container.

Without the socket mount, Docker commands inside the container cannot communicate with the host Docker daemon and will fail.

Always include '-v /var/run/docker.sock:/var/run/docker.sock' when you want Docker control inside the container.

Mounting the socket but not using a Docker image with Docker client installed.

The container needs the Docker client binary to run Docker commands; mounting the socket alone is not enough.

Use a Docker image that includes the Docker client, like 'docker:20.10.16' or the official Jenkins Docker image with Docker installed.

Running Docker commands inside the container without proper permissions.

The container user may not have permission to access the Docker socket, causing permission denied errors.

Run the container with appropriate user permissions or adjust socket permissions carefully on the host.

Summary

Mount the host Docker socket into the container to allow Docker commands inside the container to control the host Docker daemon.

Use Docker images that include the Docker client to run Docker commands inside the container.

Verify access by running 'docker ps' or starting a test container from inside the container.