Click here to Skip to main content
14,932,238 members
Articles
Article
Posted 10 May 2018

Tagged as

(untagged)

Stats

4.6K views
3 bookmarked

A Note on Jenkins

Rate me:
Please Sign up or sign in to vote.
5.00/5 (1 vote)
10 May 2018CPOL6 min read
Note on the Jenkins automation server

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.

Image 1

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.

XML
<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.

Image 2

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.

Image 3

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.

Image 4

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.

Image 5

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

Image 6

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.

Image 7

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.

Image 8

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".

Image 9

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.

Image 10

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.

Image 11

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

Image 12

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.

Image 13

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.

XML
<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.

Image 14

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.

Image 15

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.

Image 16

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 postings and I hope this note can help you one way or the other.

History

  • 5/9/2018: First revision

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Dr. Song Li
United States United States
I have been working in the IT industry for some time. It is still exciting and I am still learning. I am a happy and honest person, and I want to be your friend.

Comments and Discussions

 
-- There are no messages in this forum --