Skip to main content

Jenkins Official Docker Installation Tutorial

1. Introduction​

Recently, when setting up Jenkins on a new server, I wanted to use a newer version but ran into some issues. Turns out I hadn't read the official documentation carefully... my bad.

2. Install Docker​

yum install -y yum-utils
yum-config-manager --add-repo <https://download.docker.com/linux/centos/docker-ce.repo>
yum install docker-ce docker-ce-cli containerd.io
systemctl start docker
docker run hello-world

This is based on CentOS using yum. For Docker installation on other systems, refer to: Docker Installation

3. Install Jenkins via Docker​

This follows the official documentation: Installing Jenkins

If you're comfortable with English, you can follow that document directly for more details.

3.1 Create a Bridge Network in Docker​

Creating a bridge network enables communication between multiple containers. Yes, the current Jenkins installation requires two containers.

docker network create jenkins

3.2 Create Required Directories for Jenkins​

mkdir /dockerData/jenkins/jenkins-docker-certs
mkdir /dockerData/jenkins/jenkins-docker-certs

3.3 Create the jenkins-docker Container​

This container is created to solve communication issues between Jenkins and the host's Docker.

docker run \
  --name jenkins-docker \
  --rm \
  --detach \
  --privileged \
  --network jenkins \
  --network-alias docker \
  --env DOCKER_TLS_CERTDIR=/certs \
  --volume /dockerData/jenkins/jenkins-docker-certs:/certs/client \
  --volume /dockerData/jenkins/jenkins-docker-certs:/var/jenkins_home \
  --publish 2376:2376 \
  docker:dind \
  --storage-driver overlay2

Parameter explanations:

  • --name jenkins-docker (Optional) Creates a name for the container. By default, Docker generates a unique name.
  • --rm (Optional) Automatically removes the Docker container when it shuts down.
  • --detach (Optional) Runs the Docker container in the background.
  • --privileged Running Docker in Docker currently requires privileged access. Newer Linux kernel versions may relax this requirement.
  • --network jenkins Corresponds to the network created in the previous step.
  • --network-alias docker Makes Docker in Docker available as hostname "docker" in the jenkins network. Enables TLS in the Docker server. Recommended since we're using a privileged container, though it requires shared volumes. The environment variable --env DOCKER_TLS_CERTDIR=/certs controls the root directory for Docker TLS certificates.
  • --volume /dockerData/jenkins/jenkins-docker-certs:/certs/client Maps host directory /dockerData/jenkins/jenkins-docker-certs to container directory /certs/client
  • --volume /dockerData/jenkins/jenkins-docker-certs:/var/jenkins_home Same as above
  • --publish 2376:2376 (Optional) Exposes the Docker daemon port on the host. Useful for executing docker commands on the host to control this internal Docker daemon.
  • docker:dind The docker:dind image itself. Can be downloaded before running with: docker image pull docker:dind.
  • --storage-driver overlay2 Storage driver for Docker volumes. More details at Docker storage drivers

3.4 Customize the Official Jenkins Docker Image​

Create a file named: Dockerfile

Copy the following content:

FROM jenkins/jenkins:2.375.1
USER root
RUN apt-get update && apt-get install -y lsb-release
RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
  https://download.docker.com/linux/debian/gpg
RUN echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
  https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
RUN apt-get update && apt-get install -y docker-ce-cli
USER jenkins
RUN jenkins-plugin-cli --plugins "blueocean:1.26.0 docker-workflow:563.vd5d2e5c4007f"

In the Dockerfile's directory, execute: docker build -t myjenkins-blueocean:2.375.1-1 .

Then create the Jenkins container:

docker run \
  --name jenkins \
  --restart=on-failure \
  --detach \
  --network jenkins \
  --env DOCKER_HOST=tcp://docker:2376 \
  --env DOCKER_CERT_PATH=/certs/client \
  --env DOCKER_TLS_VERIFY=1 \
  --publish 8080:8080 \
  --publish 50000:50000 \
  --volume /dockerData/jenkins/jenkins-data:/var/jenkins_home \
  --volume /dockerData/jenkins/jenkins-docker-certs:/certs/client:ro \
  myjenkins-blueocean:2.375.1-1

Parameter explanations:

  • --restart=on-failure Always restart the container if it stops. If manually stopped, it only restarts when the Docker daemon restarts or the container is manually restarted.
  • --env DOCKER_HOST=tcp://docker:2376 --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 Environment variables for docker, docker-compose, and other Docker tools to connect to the Docker daemon from the previous step.
  • --publish 8080:8080 Maps (publishes) port 8080 of the container to port 8080 on the host. The first number is the host port, the last is the container port. If you specify -p 49000:8080, you'd access Jenkins on the host via port 49000.
  • --publish 50000:50000 Port required by Jenkins agents

At this point, the Jenkins container is created. Try accessing ip:8080 on your computer or server to see if you can reach the Jenkins service. If not, use docker logs <containerId> to check logs. Possible issues include:

Fixing Error: Container Logs Show "permission denied"​

Grant permissions to the mapped directories /dockerData/jenkins/jenkins-data and /dockerData/jenkins/jenkins-docker-certs. The permissions don't have to be 777 - choose appropriate permissions for security.

chmod 777 /dockerData/jenkins/jenkins-data
chmod 777 /dockerData/jenkins/jenkins-docker-certs

Fixing Error: open /certs/client/ca.pem: no such file or directory​

This error relates to Step 3.3 (creating jenkins-docker container). Ensure the container started successfully and that /dockerData/jenkins/jenkins-docker-certs contains the generated ca.pem file.

Fixing Error: Jenkins dial tcp: lookup docker on 127.0.0.11:53: no such host​

This error also relates to Step 3.3. Check if the container created in Step 3.3 is running.