A Note on Jenkins

Introduction

This is a note on the Jenkins automation server.

Background

In this note, I will cover the following subjects by examples.

• How to install Jenkins to a Tomcat server & how to make a backup on the Jenkins configurations and jobs
• Example 0 - This example is to find out the user that Jenkins runs on behalf and the default JAVA_HOME environment variable, etc.
• Example 1 - This example is to build a simple Maven project that I put in GitHub.
• Example 2 - This example is to deploy the WAR file built by Example 1 to a Tomcat server through Jenkins.

To install/start/administrate Jenkins, you need "administrative" permission on your computer. Your computer also needs to have internet access.

How to Install Jenkins

There are many ways to install Jenkins. In this note, I will install Jenkins to a Tomcat server running in a CentOS server. If you follow my earlier note, you can create your own CentOS server and your own Tomcat instance. But you do not need to use a CentOS server, you can use any Tomcat instance to perform the examples.

You can download Jenkins from its download page. I would recommend to download the "Generic Java package (.war)". You can then follow the instructions to deploy the WAR to Tomcat. The versions of the packages used in this note are the following:

• JAVA - jdk1.8.0_172
• Tomcat - apache-tomcat-8.5.30
• Jenkins - 2.107.3

The JENKINS_HOME

Before you deploy the WAR file to the Tomcat, you need to modify the $CATALINA_HOME/conf/context.xml file, where $CATALINA_HOME is the path to your Tomcat deployment.

<Context>
        <Environment name="JENKINS_HOME" value="/home/jenkins/" type="java.lang.String"/>
</Context>

The JENKINS_HOME path will be the directory used by Jenkins to save all the configurations and jobs.

Deploy and Run Jenkins

After adding the JENKINS_HOME variable, you can copy the jenkins.war file to the $CATALINA_HOME/webapps/ directory to finish the deployment. If your Tomcat is running, you can then go to http://localhost:8080/jenkins/ to use your Jenkins service.

By your first time to access Jenkins, it will ask you to open the initialAdminPassword file to find the initial password. After giving the initial password, you can start using Jenkins to install the "suggested plugins" and create your own users.

Backup Jenkins

According to the documentation, backup Jenkins is an easy work.

• All the settings, build logs, artifact archives are stored under the JENKINS_HOME directory. Simply archive this directory to make a back up. Similarly, restoring the data is just replacing the contents of the JENKINS_HOME directory from a back up.
• Back ups can be taken without stopping the server, but when you restore, please do stop the server.

The following is the content of the JENKINS_HOME directory after creating the first administrative user.

Run Tomcat with SUDO

Some systems may allow you to start Tomcat without administrative privilege. You may be able to start Tomcat, but the Jenkins service will not start. The following is the script that I use to start my Tomcat instance.

export JAVA_HOME=/apps/jdk1.8.0_172/
CATALINA_HOME=/apps/apache-tomcat-8.5.31
    
sh $CATALINA_HOME/bin/startup.sh

When starting Tomcat, I explicitly provided the JAVA_HOME to instruct Tomcat to use the JAVA installation of my choice.

Example 0 - whoami & JAVA_HOME

From Jenkins main menu -> New Item -> Freestyle project, you can create your first Jenkins project.

As the example 0, I want to make it absolutely simple that it has only one single Execute Shell build step.

Although this project is simple, it is probably the most important Jenkins project as it answers a few very important questions regarding the Jenkins build environment. The following is the console output after building the Example-0 project.

Conclusion

• whoami - It shows that the user that Jenkins runs on behalf is the root
• echo $JAVA_HOME - It shows that by default, the JAVA_HOME is the JAVA_HOME that you start the Tomcat server
• which git - It shows that by default, the git is the git found in the root search path. In my CentOS server, git is installed by default.

These are simple and fundamental questions, I believe that you will need to reference them whenever you encounter problems. You can also add the following bash command in the script execution.

pwd

You will find that the working directory of the Jenkins project Example-0 is $JENKINS_HOME/workspace/Example-0.

Example 1 - git & Maven

In this example, I will create a Jenkins project that pulls a Maven project from GitHub and builds it with Maven.

Install & Inform Jenkins about Maven

In order to build a Maven project, I need to make Maven available in my computer. There are many way to install Maven, but I chose to download it from Maven download page. I want to have absolute control on the instance of Maven used.

After downloading the tar.gz, I just un-zip it to the /apps directory. I need to let Jenkins know that there is an installation of Maven on the computer. From Jenkins main menu, click on Manage Jenkins -> Global Tool Configuration -> Maven -> Maven installations.

You can give a name and the location of this Maven installation so Jenkins can use it to build projects.

Example-1 & Maven Build

You can create the Freestyle project Example-1. In the Source Code Management section, you can tell Jenkins to use git to pull the code. The Repository URL is https://github.com/BigMountainTiger/lu-decomposition.git. Because it is a public repository, you do not need any permission to pull the code from the repository.

In the Build section, you can add the Invoke top-level Maven targets build step. You can tell Jenkins to use the Maven installation that you configured in the previous step to build the project.

If everything goes well, you will find that the code is pulled from GitHub and Maven runs successfully after initiating the build.

Example 2 - Deploy to a Container

The goal of Example 2 is to deploy the lu-decomposition.war file generated by the Example 1 to a Tomcat server through Jenkins.

In this note, I will deploy the WAR file to the same Tomcat instance that runs Jenkins for simplicity. We need to modify the tomcat-users.xml file in the conf/ directory to add the user that can perform the remote deployment. We need to restart Tomcat to allow this configuration to take effect.

<tomcat-users xmlns="http://tomcat.apache.org/xml" version="1.0">
    <user username="jenkins" password="pwd12345" roles="manager-script" />
</tomcat-users>

Jenkins relies on the Deploy to container Plugin to make the remote deployment. From Jenkins main menu -> Manage Jenkins -> Manage Plugins -> Installed and search for Deploy to make sure the plugin is installed. If it is not installed, you need to install it.

We can then add a Post-build action to Example 1. We need to tell Jenkins the path to the war file and the credential needed for the deployment.

We can then initiate a Jenkins build. If everything goes well, we can go to http://localhost:8080/lu-decomposition/ and see that the deployment is successful and the web page is functioning.

How the "Deploy to container Plugin" Works?

I actually do not know exactly how the Deploy to container Plugin works. But if you issue the following command, you can undeploy the web application.

wget --http-user=jenkins --http-password=pwd12345 
"http://localhost:8080/manager/text/undeploy?path=/lu-decomposition" -O -

If you issue the following commands, you can deploy the WAR file to Tomcat.

WAR=/home/jenkins/workspace/Example-1/target/lu-decomposition.war
wget --http-user=jenkins --http-password=pwd12345 
"http://localhost:8080/manager/text/deploy?war=file:$WAR&path=/lu-decomposition" -O 

Points of Interest

• This is a note on the Jenkins automation server.
• I hope you like my posts and I hope this note can help you one way or the other.

History

• 10^th May, 2018: First revision