The deployment of Jenkins within a Dockerized environment represents a paradigm shift in how Continuous Integration and Continuous Delivery (CI/CD) pipelines are architected. By leveraging containerization, developers can decouple the Jenkins application from the underlying host operating system, ensuring that the environment remains immutable, portable, and easily reproducible across various stages of the software development lifecycle. Docker provides the essential abstraction layer required to run Jenkins as a read-only image, which is then instantiated as a temporary container. This architectural approach eliminates the "it works on my machine" syndrome, as the exact same image used in a local development environment is promoted through testing and into production.
The integration of Jenkins and Docker is not merely about running the Jenkins controller; it extends to the orchestration of build agents and the ability for Jenkins to spawn other Docker containers to execute build steps. This creates a recursive relationship where Docker manages Jenkins, and Jenkins, in turn, manages Docker. To achieve this, a sophisticated configuration involving network aliases, volume persistence, and privileged access for Docker-in-Docker (DinD) scenarios must be implemented. The transition from traditional bare-metal installations to containerized deployments allows for rapid scaling, simplified upgrades through image replacement, and a more granular approach to resource management.
Fundamental Concepts of Dockerized Environments
To successfully deploy Jenkins, one must first understand the core mechanics of the Docker platform. Docker operates by creating isolated environments known as containers. These containers are the running instances of Docker images.
A Docker image is a static, read-only template that contains the application code, libraries, and system configurations necessary to run the software. In the context of Jenkins, the image is stored permanently and is only updated when a new version is published by the Jenkins project. This ensures that every instance of a specific image tag is identical.
Conversely, a Docker container is the ephemeral, running instance of that image. While images are persistent, containers are temporary by nature. This distinction is critical for Jenkins administrators: while the container can be destroyed and recreated without affecting the image, any data written inside the container's writable layer is lost upon deletion. Therefore, the separation of the application (the image) from the data (the volume) is the cornerstone of a production-ready Jenkins setup.
The universality of Docker means that a Jenkins image can be deployed on any supported operating system or cloud service. This includes:
- macOS
- Linux
- Windows
- Amazon Web Services (AWS)
- Microsoft Azure
For those installing Docker on Linux, a critical administrative requirement is ensuring that Docker is configured to be managed as a non-root user. This is a security imperative to prevent the container engine from granting unrestricted root access to the host system, which could lead to catastrophic security breaches if a container is compromised.
Hardware and Software Prerequisites
Before executing the deployment commands, the host environment must meet specific resource thresholds to ensure the Jenkins controller and its subsequent agents operate without performance degradation.
| Configuration Level | RAM Requirement | Drive Space Requirement | Use Case |
|---|---|---|---|
| Minimum | 256 MB | 1 GB (10 GB recommended) | Basic testing/POC |
| Small Team | 4 GB+ | 50 GB+ | Standard team development |
| Comprehensive | Refer to Hardware Page | Refer to Hardware Page | Enterprise production |
From a software perspective, the primary requirement is a functional installation of the Docker engine. Users are encouraged to use the official jenkins/jenkins image from Docker Hub, as it provides the Long-Term Support (LTS) release. The LTS release is specifically engineered for production environments, offering a balance of stability and updated features.
It is important to note that the standard official image is a "lean" version. It does not come bundled with the Docker CLI, nor does it include the Blue Ocean plugins, which are essential for modern, visual pipeline management. To unlock the full potential of Jenkins-Docker integration, a customized image must be constructed.
Orchestrating the Jenkins Environment
The deployment process begins with the creation of a dedicated network. This allows the Jenkins controller to communicate with other containers, such as the Docker-in-Docker (DinD) service, using a stable network alias.
The first command to execute is:
docker network create jenkins
This creates a bridge network that isolates the Jenkins ecosystem from other containers on the host, providing a layer of security and organized DNS resolution.
Implementing Docker-in-Docker (DinD) for Advanced Pipelines
For Jenkins to execute Docker commands inside its own nodes (such as building a Docker image as part of a CI pipeline), it requires access to a Docker daemon. This is achieved by running a separate docker:dind container.
The following command initializes the DinD service:
docker run \
--name jenkins-docker \
--rm \
--detach \
--privileged \
--network jenkins \
--network-alias docker \
--env DOCKER_TLS_CERTDIR=/certs \
--volume jenkins-docker-certs:/certs/client \
--volume jenkins-data:/var/jenkins_home \
--publish 2376:2376 \
docker:dind \
--storage-driver overlay2
The technical specifications of this command are detailed below:
--name jenkins-docker: Assigns a human-readable name to the container for easier management.--rm: Ensures the container is removed automatically when stopped, preventing "container clutter."--detach: Runs the container in the background (detached mode).--privileged: Grants the container root access to the host's kernel features, which is mandatory for running a Docker daemon inside a container.--network jenkins: Attaches the container to the previously created Jenkins network.--network-alias docker: This is a critical DNS mapping. It allows the Jenkins controller to reach the Docker daemon using the hostnamedockerinstead of a volatile IP address.--env DOCKER_TLS_CERTDIR=/certs: Sets the environment variable for TLS certificate storage, ensuring secure communication.--volume jenkins-docker-certs:/certs/client: Maps the certificates to a volume so they can be shared with the Jenkins controller.--volume jenkins-data:/var/jenkins_home: Ensures shared access to the Jenkins home directory.--publish 2376:2376: Exposes the secure Docker daemon port to the host.--storage-driver overlay2: Specifies the storage driver for the containers created within the DinD environment, optimizing disk I/O.
Customizing the Jenkins Image with Blue Ocean and Docker CLI
Since the default jenkins/jenkins image lacks the Docker CLI and Blue Ocean plugins, a custom image must be built using a Dockerfile. This allows the administrator to inject the necessary tools during the image construction phase.
To create a customized version, a Dockerfile is created with the following technical specifications:
dockerfile
FROM jenkins/jenkins:2.555.1-jdk21
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 docker-workflow json-path-api"
The logic behind this Dockerfile is as follows:
- It starts from the LTS JDK 21 base image.
- It switches to the
rootuser to perform system-level installations of the Docker CLI. - It configures the official Docker repository for Debian, ensuring that the
docker-ce-cliis installed from a trusted source. - It switches back to the
jenkinsuser to maintain the principle of least privilege. - It uses the
jenkins-plugin-clito pre-install the Blue Ocean, Docker Workflow, and JSON Path API plugins, removing the need to install them manually via the GUI after startup.
To build this image, the following command is used:
docker build -t myjenkins-blueocean:2.555.1-1 .
This process tags the image as myjenkins-blueocean:2.555.1-1, making it easily identifiable for future deployments.
Deploying the Jenkins Controller
Once the custom image is built and the DinD service is running, the Jenkins controller can be instantiated.
Standard Deployment (Basic)
For a basic setup without customization, the following command is used:
docker run -p 8080:8080 -p 50000:50000 --restart=on-failure jenkins/jenkins:lts-jdk21
In this configuration:
- Port 8080 is used for the web interface.
- Port 50000 is used for communication between the controller and its agents.
- --restart=on-failure ensures that the Jenkins server recovers automatically from crashes.
Advanced Deployment (Full Stack)
To deploy the customized Blue Ocean image with full Docker integration, the following command is executed:
docker run --name jenkins-blueocean --restart=on-failure --detach ^
--network jenkins --env DOCKER_HOST=tcp://docker:2376 ^
--env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 ^
--volume jenkins-data:/var/jenkins_home ^
--volume jenkins-docker-certs:/certs/client:ro ^
--publish 8080:8080 --publish 50000:50000 myjenkins-blueocean:2.555.1-1
The technical implications of these flags are:
--network jenkins: Connects the controller to the shared network where the DinD container resides.--env DOCKER_HOST=tcp://docker:2376: Tells Jenkins to send Docker API requests to the container nameddockeron port2376.--env DOCKER_TLS_VERIFY=1: Enables TLS verification for secure communication with the daemon.--volume jenkins-data:/var/jenkins_home: Persists all Jenkins data (plugins, jobs, configs) in a Docker volume.--volume jenkins-docker-certs:/certs/client:ro: Mounts the TLS certificates as read-only (ro), allowing Jenkins to authenticate with the DinD service.
Data Persistence and Volume Management
The directory /var/jenkins_home is the most critical path in a Jenkins deployment. This is where all workspace data, configuration files, and installed plugins reside. Because containers are ephemeral, any data stored here without a volume will be lost when the container is updated or deleted.
Docker Volumes vs. Bind Mounts
There are two primary methods for persisting Jenkins data:
- Docker Volumes (Recommended):
Using the syntax-v jenkins_home:/var/jenkins_homecreates a managed volume. Docker handles the underlying filesystem, and the data persists even if the container is destroyed.
docker run -p 8080:8080 -p 50000:50000 --restart=on-failure -v jenkins_home:/var/jenkins_home jenkins/jenkins:lts-jdk21
- Bind Mounts (Not Recommended):
A bind mount maps a specific folder on the host machine (e.g.,/home/user/jenkins) directly into the container. While this allows for easy manual backups of the folder, it often leads to critical file permission issues. This happens because thejenkinsuser inside the container (UID 1000) may not have the necessary permissions to read or write to the host folder.
If a bind mount is absolutely required, the host directory must be made accessible to the jenkins user (UID 1000), or the container must be started with the -u some_other_user parameter.
Post-Installation and Troubleshooting
After the container is started, the administrator must perform the initial setup.
Retrieving the Initial Admin Password
Jenkins generates a unique password for the first login for security reasons. This password can be retrieved in two ways:
Via the container logs:
docker logs <docker-container-name>Via a direct shell command using
docker exec:
docker exec <jenkins_container_id_or_name> cat /var/jenkins_home/secrets/initialAdminPassword
Interacting with the Container
To enter the Jenkins container and execute commands directly in the bash shell, use the following command:
docker exec -it jenkins-blueocean bash
The -it flag provides an interactive terminal, allowing the user to browse the filesystem or manually debug plugin installations.
Troubleshooting Connectivity
If the user encounters the message "This Jenkins instance appears to be offline," it is typically a DNS configuration issue. This is often caused by incorrect network mapping or a failure in the docker:dind service. Verifying that the docker network alias is correctly resolved is the first step in troubleshooting this error.
Legacy Image Deprecation
It is vital to distinguish between the current jenkins/jenkins images and the legacy jenkins image. The original jenkins image found on some parts of Docker Hub has been deprecated for over two years. It is no longer maintained by the Jenkins Community and does not receive security updates.
Historical images (such as those found under the jenkins tag) are provided only for archival reasons. All production environments must use jenkins/jenkins:lts to ensure they are running a supported, secure, and optimized version of the software.
Conclusion
The deployment of Jenkins via Docker transforms the CI/CD server from a fragile, stateful installation into a flexible, scalable microservice. By separating the immutable image from the persistent volume, organizations can achieve a high degree of reliability and ease of maintenance. The use of the docker:dind architecture allows Jenkins to leverage the full power of containerization for its own build processes, creating a seamless loop of container-based automation.
The technical requirements for a successful deployment—ranging from the creation of a dedicated Docker network to the construction of a customized image containing the Docker CLI and Blue Ocean plugins—ensure that the system is both secure and functional. While bind mounts offer a tempting level of visibility into the host filesystem, the inherent permission risks make Docker-managed volumes the only viable choice for professional environments. Ultimately, the transition to jenkins/jenkins:lts and the implementation of detached, auto-restarting containers provide the stability required for enterprise-grade continuous integration.