This is a note on the Jenkins automation server.
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
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.
<Environment name="JENKINS_HOME" value="/home/jenkins/" type="java.lang.String"/>
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.
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.
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.
whoami" - It shows that the user that Jenkins runs on behalf is the "
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.
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" />
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.
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.