In this article, you will learn how to build and push Docker images to Docker Hub using Jenkins Pipeline. It covers the concepts of Jenkins Pipeline and how to set it up in your local machine. Any DevOps engineer who wants to learn Jenkins can easily follow this article and implement the Jenkins Pipeline.
Jenkins is an open-source Java-based continuous integration/continuous delivery and deployment (CI/CD) open-source automation platform. Jenkins is a core component in DevOps infrastructure. It automates the software development tasks from building and testing to deploying software into the production environment.
Getting Started with Jenkins
Jenkins uses pipelines to implement the CI/CD tasks in the DevOps environment. The Jenkins platform has plugins that enable DevOps engineers and organizations to integrate different software tools with Jenkins. Jenkins uses source control management (SCM) software to track changes in the source code repository such as Git. You will use GitHub as your source code repository. Jenkins also uses a Jenkinsfile to create a Jenkins Pipeline. Jenkinsfile is a pipeline as a code file. It contains stages and steps for the Jenkins CI/CD pipeline.
Jenkins continually builds, tests, delivers, deploys, and integrates software and applications. It makes it easier for DevOps engineers and teams to implement continuous integration. It ensures that the end users always have the new versions and builds of the software or application.
To get started with Jenkins, you are required to have the following:
1. GitHub account
You will use GitHub as your source code repository. You will create a GitHub repository and then push your project files to this remote repository.
Your project will have a `Jenkinsfile` and a `Dockerfile`. The `Jenkinsfile` will define the stages for the Jenkins Pipeline.
The `Dockerfile` will have commands for building a Docker image.
2. Docker Hub account
Jenkins Pipeline will push the Docker image to your Docker Hub repository. In the Jenkinsfile, you will add a stage to instruct the Jenkins Pipeline to push the Docker image to your Docker Hub repository. We will create the Jenkinsfile later. Let’s start by installing Jenkins.
Installing Jenkins
In this tutorial, we will install and run Jenkins in Docker. Ensure that you have Docker Desktop running on your machine. You will start by building a Docker image for Jenkins. You will then run the Docker image to start the Docker container for Jenkins. In your PC, create a Dockerfile and add the following Docker snippet:
FROM jenkins/jenkins USER root RUN apt-get update && apt-get install -g docker-ce-cli RUN apt-get update && apt-get install -g lsb-release 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 curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \ https://download.docker.com/linux/debian/gpg USER jenkins
Docker Engine will use the Dockerfile above to build the Jenkins Docker image. Run the following Docker command in your terminal:
docker build -t jenkins-docker .
The command above displays the following in the console:
Starting the Jenkins Docker Container
To start the Jenkins Docker Container, run the following Docker command:
docker run -p 8080:8080 -p 50000:50000 --restart=on-failure -d -v jenkins_home:/var/jenkins_home jenkins-docker
When you execute the `Docker run` command in your terminal:
- It will expose the Jenkins Docker container on port 8080.
- It also exposes port 5000 to ensure Jenkins master and slaves nodes communicate.
- It uses a `–restart=on-failure` argument to ensure the Jenkins Docker container stops when there is a failure in the nodes. `-d` runs the Jenkins Container in detached mode (runs the container in the background).
- It creates a Docker volume (jenkins_home:/var/jenkins_home) to store or persist the data of Jenkins. It will store all the Jenkins plugins and configuration tools you will install on the Jenkins controller platform.
The command will start and run Jenkins on localhost:8080. Type the URL in to access the running Jenkins Docker Container:
The next step is to unlock Jenkins using the administrator password.
Unlocking Jenkins
To get the administrator password, run the following command in your terminal:
docker logs jenkins-docker
The command will output the administrator password in your terminal as shown below:
Copy the administrator password from the terminal and paste it to the Jenkins UI. After unlocking Jenkins, it will launch the `Getting Started page. You will then click `Install suggested plugins`. The getting started page is shown below:
It will then show the plugins installation progress:
After the plugin installation is complete, you will be required to create your first admin user:
You will use this admin user to login into the Jenkins platform.
Instance Configuration
After creating your first admin user, you will add the Jenkins URL as shown below:
After adding the Jenkins URL to the instance configuration page, your Jenkins container will be ready:
The setup for Jenkins is complete, and Jenkins is ready:
To start using Jenkins, click the button `Start using Jenkins`. You will be redirected to the Jenkins dashboard as shown below:
The next step is to create a new GitHub repository.
Creating a New GitHub Repository
Login into your GitHub account and create a new repository as shown below:
After creating the new repository, we need to add the GitHub credentials to Jenkins.
Add the GitHub Credentials to Jenkins
Jenkins will use the GitHub credentials for authentication when creating the Jenkins Pipeline from the source code repository. You will add your GitHub username and password. Follow the steps shown in the images below:
First Step: In your Jenkins Dashboard, click `Manage Jenkins`
Second Step: Click `Manage Credentials
Third Step: Click `New Credentials
Fourth Step: Add `Username`, `Password`, `ID`, and `Description`
Our credentials are now ready to use. The next step is to add the Docker Hub credentials to Jenkins.
Add the Docker Hub Credentials to Jenkins
You could use your password for your Docker Hub credentials, but it’s better to create an access token to login into Docker Hub. The Jenkins pipeline will use your Docker Hub username and access token when pushing the Docker image to the Docker Hub repository. To create the Docker Hub access token, follow the steps below:
First Step: Log into your Docker Hub account
Second Step: Click `Account Settings`
Third Step: Click `Security`
Fourth Step: Click `New Access Token`
Fifth Step: Add Access Token Description
After adding the access token description, click `Generate`. Copy and save the generated access token. You will go back to the Jenkins `Manage Credentials` and add the new credentials as shown below:
Our two credentials are now ready to use. The next step is to create the Project files.
Creating Project Files
In your PC, create a new folder named `jenkins-docker`. In the folder, create a file named `Dockerfile` without any extension and add the following Docker command:
FROM alpine:3.13.5
This command will instruct Docker to build an Alpine-based Docker image. We have a very simple Dockerfile with only a single instruction/command. Next, create a file named `Jenkinsfile` without any extension. Open the file and the following Jenkins Pipeline stages:
pipeline {
agent any
options {
buildDiscarder(logRotator(numToKeepStr: '5'))
}
environment {
DOCKERHUB_CREDENTIALS = credentials('dockerhub')
}
stages {
stage('Build') {
steps {
sh 'docker build -t lloydmatereke/jenkins-docker-hub .'
}
}
stage('Login') {
steps {
sh 'echo $DOCKERHUB_CREDENTIALS_PSW | docker login -u $DOCKERHUB_CREDENTIALS_USR --password-stdin'
}
}
stage('Push') {
steps {
sh 'docker push lloydmatereke/jenkins-docker-hub'
}
}
}
post {
always {
sh 'docker logout'
}
}
}
The Jenkinsfile will create a Jenkins Pipeline with three stages: `Build`, `Login`, and `Push`.
Build stage
Here, you will use the Dockerfile to build an Alpine-based Docker image. It will name the Docker image `lloydmatereke/jenkins-docker-hub`. Replace this name with your Docker Hub username.
Login stage
At this stage you will use the `DOCKERHUB_CREDENTIALS ` credentials to login into the Docker Hub account. Note: My GitHub credential is named `dockerhub`. Ensure you replace this with your credentials name.
Push stage
Then you will push the `lloydmatereke/jenkins-docker-hub` Docker image to Docker Hub.
The Jenkins Pipeline also has a post-logout action. It uses the `docker logout` to log out from your Docker Hub account. The next is to push the project files to GitHub.
Pushing the Project Files to GitHub
To push the Project files to GitHub, use the Git commands listed in the image below:
After applying the Git commands in your, the project files will be pushed to GitHub as shown below:
The next step is to create a Jenkins job to run the Jenkins Pipeline.
Creating a Jenkins Job
To create a Jenkins job, follow the steps shown in the images below.
Step Open: Go back to the Jenkins dashboard and click `Create a job`
Second Step: Enter the item name
Third Select the `Multibranch Pipeline`, then click `OK`
4. Configure the Pipeline
You add the `GitHub credentials` and `Repository HTTPS URL` to configure the Jenkins pipeline:
Scanning the Repository
After configuring the Pipeline, Jenkins starts scanning the repository until it finds a `Jenkinsfile` as shown below:
From the image above Jenkins, Jenkins has scanned the repository and found a `Jenkinsfile` in the `main` branch. Jenkins will use `Jenkinsfile` to run the Jenkins pipeline.
Running the Jenkins Pipeline
After scanning the repository, Jenkins will start the Jenkins pipeline using the `Jenkinsfile`. To get the Pipeline output, click on the `Console Output` as shown below:
After clicking the output, it displays the following:
The output above shows the Jenkins Pipeline has started running. It will then go through all the pipeline stages and implement the steps. After completing the stages, it will either output a `SUCCESS` or `FAILURE` message:
From the image above, our Jenkins pipeline displays a `SUCCESS` message. It shows that the Jenkins Pipeline had finished building and pushing the Docker image to Docker Hub. It finally logged out of the Docker Hub account. All the stages in the Pipeline are shown in the image below:
You can then login into your Docker Hub account to see the pushed Docker image:
The Jenkins pipeline pushed the Docker image to Docker Hub. We have successfully used the Jenkins Pipeline to build and push a Docker image to Docker Hub.
Conclusion
In this tutorial, you learned how to build and push a Docker image to Docker Hub using Jenkins Pipeline. You can learn more about Docker Image Layers here.
- Started by installing and running Jenkins in Docker.
- Used the Dockerfile to build the Jenkins Docker image.
- Started the Docker image and launched a Jenkins Docker container.
- Followed the steps of unlocking Jenkins and creating the first admin user.
- Added the Docker Hub and GitHub Credentials to Jenkins for authentication.
- Created project files (Jenkinsfile and a Dockerfile) and pushed them to GitHub.
- Used a Jenkinsfile to run the Jenkins Pipeline
- Pushed a Docker image to Docker Hub.
