This blog is divided into two sections, in the first section we will provide step by step instructions to setup a demo environment with Jenkins based CI/CD pipeline which will build the web application, deploy it to Integration environment  and run sonar analysis for the master branch. The second section provides overview of the Jenkins Pipeline. As per the Jenkins User Documentation, Jenkins Pipeline (or simply "Pipeline") is a suite of plugins which supports implementing and integrating continuous delivery pipelines into Jenkins. the definition of a Jenkins Pipeline is written into a text file (called a Jenkinsfile) which in turn is checked into a project’s source control repository.  This is the foundation of "Pipeline-as-Code"; treating the continuous delivery pipeline a part of the application to be versioned and reviewed like any other code. You can read more about Jenkins pipeline here.

The below diagram shows the CI workflow. Jenkins polls the repository for any changes, once a changes is detected Jenkins runs the build and create the artifact. Jenkins also pushes the code to SonarQube for code analysis. After the artifact is built, a job is triggered to deploy the artifact on the Integration environment.  We recommend setting up "Webhooks" instead of continuously polling the repository to trigger the build when changes are pushed to the repository.

jenkins_pipeline.png

We have provided a simple step-by-step tutorial using which you should be able to setup a demo environment with Jenkins, SonarQube and Tomcat.  The mentioned tools/applications will be run as docker containers. You can also use non Dockerized versions of the tools if desired.

Below video walks through the steps to setup the demo environment.  The source code to reproduce the demo is located here. You can also follow the instructions on this page to setup the demo environment.

Requirements:

  • Docker for Mac, Windows, or Linux

Setup Docker Containers

To begin with the tutorial, clone the repository from Github "https://github.com/Addteq/jenkins-pipeline-with-docker" .

git clone https://bitbucket.org/addteq/jenkins-pipeline-with-docker.git

Navigate to the directory "jenkins-pipeline-with-docker" and run the below docker command to  setup Jenkins, Sonarqube and Tomcat containers.

sudo docker-compose up -d

To view all the running containers run the below command

sudo docker-compose ps

Expected output

               Name                               Command               State                 Ports               
------------------------------------------------------------------------------------------------------------------
jenkinspipelinewithdocker_jenkins_1     /bin/tini -- /usr/local/bi ...   Up      50000/tcp, 0.0.0.0:8080->8080/tcp 
jenkinspipelinewithdocker_sonarqube_1   ./bin/run.sh                     Up      0.0.0.0:9000->9000/tcp            
jenkinspipelinewithdocker_tomcat_1      /run.sh                          Up      0.0.0.0:10000->8080/tcp      

Configure the "Jenkins" instance

  1. Navigate to the below URL to connect to your Jenkins instance.
http://localhost:8080

You should see similar screen if you are connecting first time to the Jenkins instance.

jenkins1.png

      2. Connect to the Jenkins container to get the initial admin password.

sudo docker-compose exec --user root jenkins cat /var/jenkins_home/secrets/initialAdminPassword

       3. Install Maven on the jenkins container using below commands. We will be using maven to build the project in the demo. Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.

sudo docker-compose exec --user root jenkins apt-get update
sudo docker-compose exec --user root jenkins apt-get -y install maven

        4. Install Jenkins suggested plugins.

jenkins2.png

       5. Create the Admin user.


jenkins3.png

       6. Go to Manage Jenkins Manage plugins and Install the plugins "Deploy to container" and  "Copy Artifact Plugin" from the "Available" which are required for the demo. These plugins are used to copy the artifacts from the upstream job and deploy to the Tomcat server.


jenkins4.png

       7. Add label "jenkins" on the master server.  Go to Manage Jenkins → Manage Nodes and confligure the master node. We add the label as we restrict the stages to run on the agents with the label "jenkins" in the JenkinsFile.

jenkins5.png


Setup Jenkins Project

       1. Go to Jenkins and click on "New item". Enter the job name as  "GameofLife_pipeline". Select the "Multibranch Pipeline" as the Project type and click on "OK".

jenkins6.png

       2. Under Branch Sources, configure the Git repository. We will be using the repo "jenkins-pipeline-with-docker" which has already been created for the demo.  Select "GIT" from the dropdown and 

            enter the project repository as https://bitbucket.org/addteq/jenkins-pipeline-with-docker.git . 

jenkins13.png

       3. Navigate  to jenkins and click on "New item" and create a job called "Tomcat deploy to Integration".  Select the "Freestyle project" as the item type and click on "OK". This is the Jenkins job to deploy the built artifact on the tomcat container.             Please make sure the name of the job matches the one mentioned in the JenkinsFile. JenkinsFile is located in the repo https://bitbucket.org/addteq/jenkins-pipeline-with-docker.git 

jenkins8.png

       4. Configure the General section and select "This build is parameterized" and add the variable as below. Select "String Parameter" as the parameter type and enter the name of the parameter as "BRANCH_NAME" and the default value as develop. We specify the  variable to copy the artifact from the correct branch.

jenkins9.png

       5. Configure  the build step of the project to copy the artifact from the upstream project. Enter the name of the artiffact to be copied as "gameoflife-web/target/gameoflife.war

jenkins10.png

       6. Add the post-build step tp deploy to the Tomcat container and save the changes. Add the admin credentials for Tomcat and select it from the dropdown. Enter the context path and the Tomcat URL as "http://tomcat:8080"

jenkins12.png

       7. After these jobs are created, you should see a build running on the master branch. If the build is not started automatically, you can manually click "Scan multipbranch pipeline Now". We have configured the jenkins job to scan the  repository every 2 minutes in the tutorial. We can also setup webhooks in Github instead of polling the Git repository. 

jenkins14.png


View Build Results

Once the build is completed, you can navigate  to the URL "http://localhost:9000" to view the sonar scan results and browse the application using the URL : http://localhost:10000/gameoflife/

In Jenkins, Stage View provides extended visualization of Pipeline build history on the index page of a flow project . This represents the stages which are configured in the Jenkins Pipeline.

jenkins15.png

Overview of Jenkins Pipeline

In the current pipeline demo, we have use  the "Game of life" maven project. We configured three stages as below. Additional stages can be created by updating the "Jenkinsfile".

pipeline {
agent none
stages {
 stage('Build and Test') {
   agent {node{
   label "jenkins"}
         }

   steps {
   sh 'mvn clean package'
   sh 'echo "build ran"'
   archiveArtifacts artifacts: 'gameoflife-web/target/gameoflife.war', fingerprint:true
   junit '**/target/surefire-reports/*.xml'

        }
}
 stage ('Sonar Analysis') {
   agent {node{
   label "jenkins"}
         }

   steps {
   sh 'echo "running sonar analysis"'
   sh "mvn sonar:sonar -Dsonar.host.url=http://sonarqube:9000 -Dsonar.branch=${env.BRANCH_NAME}"
         }
}
 stage ('Deploy to Integration') {
   agent {node{
   label "jenkins"}
         }
   steps {
   build job:'../Tomcat deploy to Integration' , parameters:[string(name: 'BRANCH_NAME', value: "${env.BRANCH_NAME}")]
         }
}
        }
}



Stage 1 : Build and test the artifact.

In this stage, we use maven commands to build and test the artifact.

mvn clean package


Stage 2 : Run sonar analysis 

In this stage we will run the code analysis , the scan results will be then displayed in SonarQube. We will pass the Sonar host URL and Sonar branch as parameters,

mvn sonar:sonar

Stage 3 : Deploy to Integration.

in this stage, we execute the  job "Tomcat deploy to Integration" configured which uses the plugin to copy the artifact from the upstream job and deploy it to the Tomcat container. 


Conclusion:

By the end of this tutorial you should have a demo enviroment setup for automated deployment using Jenkins Pipeline. Last part of the blog gives a quick overview of the Jenkinsfile used in the demo.