How to Build and Push Docker Images to Docker Hub using Jenkins Pipeline

17805 VIEWS

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:

Docker 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:

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:

admin password in terminal

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:

Jenkins Getting Started page

It will then show the plugins installation progress:

After the plugin installation is complete, you will be required to create your first admin user:

Create Jenkins 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:

Welcome to Jenkins

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:

Jenkins Pipeline console output

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:

Stages in the Jenkins Pipeline

 

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.

  1. Started by installing and running Jenkins in Docker.
  2. Used the Dockerfile to build the Jenkins Docker image.
  3. Started the Docker image and launched a Jenkins Docker container.
  4. Followed the steps of unlocking Jenkins and creating the first admin user.
  5. Added the Docker Hub and GitHub Credentials to Jenkins for authentication.
  6. Created project files (Jenkinsfile and a Dockerfile) and pushed them to GitHub.
  7. Used a Jenkinsfile to run the Jenkins Pipeline
  8. Pushed a Docker image to Docker Hub.

Lloyd Matereke is a DevOps engineer and technical writer. He has experience with Docker, Docker Compose, Kubernetes, CI/CD tools and Infrastructure as Code tools. He has deployed multiple containerized applications to Kubernetes cluster. He also has experience with Kubernetes architecture, Jenkins and creating infrastructure using Terraform. He has written various technical articles explaining DevOps tools and concepts.


Discussion

Leave a Comment

Your email address will not be published. Required fields are marked *

Menu
Skip to toolbar