Jenkins with access to hosts Docker engine

This tutorial provider Docker Compose configuration for running Jenkins inside a container with Docker client that controls host machines Docker engine using a socket. This works well in development environments as you can inspect containers created by Jenkins from the host system.

Note that by default each of the example Docker Compose configurations will create their own volumes for the data. This might not be what you want, if you want to use configuration from Integrating Jenkins and SonarQube as well. In order to use the same volumes for every docker compose configuration, run docker compose with -p (or --project-name) option. This can also be done by setting COMPOSE_PROJECT_NAME environment variable:

export COMPOSE_PROJECT_NAME=jenkins

Jenkins image with Docker client

To be able run Docker commands from inside the Jenkins container, we will need to install the Docker client. This can be done with a suitable Dockerfile:

Dockerfile

FROM jenkins/jenkins:lts-alpine

# Change user to root in order to have permissions to install packages.
USER root

# Only Docker client is required inside the Jenkins container as the host systems Docker engine is used from inside the container.
RUN apk add docker-cli

# Note that the user is not switched back to jenkins here. This is to avoid problems with docker socket permissions.
# Do not use root user in production. Instead, match group IDs of docker groups in host and container and add jenkins user to docker group.

Jenkins container with access to hosts Docker engine

When running Jenkins in a container, we will want to define ports and volumes. To do this, we will use a docker-compose.yml configuration:

docker-compose.yml

services:
  jenkins:
    build: .
    ports:
      # Web user interface
      - 8080:8080
      # Java agents
      - 50000:50000
    volumes:
      # Persistent volume for the Jenkins data
      - "jenkins.data:/var/jenkins_home"
      # Host systems docker socket
      - "/var/run/docker.sock:/var/run/docker.sock"

volumes:
  jenkins.data:

These files are available in the repository that provides this website. In order to run Jenkins container with Docker-in-Docker support, cd into docs/tutorials/jenkins/jenkins-host-docker directory and run docker compose up.

cd docs/tutorials/jenkins/jenkins-host-docker

# If you want to see logs in the current terminal
docker compose up --build

# Or if you want to run the container in the background
docker compose up --build --detach

The initial admin password can be easily printed with docker compose exec:

docker compose exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

In order to get started with Jenkins, the suggested plugins are often good a starting point. If you are planning to create pipeline projects with stages running in on-demand Docker containers, you will also need Docker Pipeline plugin. This can be installed through the Manage Jenkins > Manage plugins menu.