Abstract
The purpose of this tutorial is to get you up and running with Jenkins as quickly as possible. Jenkins is an extendable open source continuous integration server. In this tutorial we will setup a stock Jenkins installation using runit for service management.
What You Will Learn
- How to install Jenkins
- How to setup runit to manage Jenkins
0. Prerequisites
Make sure that you java Java installed on your system. To verify that Java is installed execute the command:
# java -version
You should see some output that looks something like this:
java version "1.7.0_25"
OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1~deb7u1)
OpenJDK Client VM (build 23.7-b01, mixed mode, sharing)
If you see an error, consult the documentation on how to install Java for your platform.
Additionally, you will need runit installed. If you are unfamiliar with runit, you may want to read the following tutorial before continuing.
Getting started with the runit - a UNIX init scheme with service supervision
1. Installing Jenkins
The first thing that we need to do is create a user to run Jenkins with. Add a new user named jenkins using the method provided by your Linux distrobution. For example, on Debain you can add the user with the the following command:
# adduser jenkins
Next, let's create a directory to install Jenkins in and change its ownershipt to the jenkins user. You can install Jenkins in any location you wish. I like to install it in the /opt directory.
# mkdir /opt/jenkins
# chown jenkins:jenkins /opt/jenkins
The only artifact that we need to install jenkins is the latest version of jenkins.war from the Jenkins CI Web Site.
Change to the jenkins user, navigate to the Jenkins installation directory, and download jenkins.war.
# su jenkins
# cd /opt/jenkins
# wget http://mirrors.jenkins-ci.org/war/latest/jenkins.war
Jenkins is provided as an executable war with an embedded web server. There is no need to deploy the war in a servlet container such as Tomcat.
Start Jenkins by running the following command:
# java -jar jenkins.war
You should see output displaying the progress of Jenkins starting up. Once you see a message like the one shown below, Jenkins will be available.
INFO: Jenkins is fully up and running
When you started Jenkins, the war file was expanded to the JENKINS_HOME directory. Because we did not define this environment variable, Jenkins defaults to ~/.jenkins. In our case this is would be /home/jenkins/.jenkins. This directory will be used to store all of the data needed by Jenkins.
Open a web browser and navigate to port 8080 on your host, you should be greeted by the Jenkins home page. Take a few minutes to explore the application.
When you are done exploring Jenkins, go ahead and shut it down by entering Ctrl-c in the terminal.
2. Configuring runit to manage Jenkins
While the steps described above are great to fire up Jenkins and start exploring, when deploying Jenkins for use in production this simple approach has several issues. First, to ensure high availability of our CI server we need a way to automate the management of the Jenkins process. Second, we need a way to manage logging. Finally, it is often useful to provide environment variables for customizing how Jenkins is run. By configuring Jenkins as a managed service with runit, we can take care of all of these needs.
If you are still acting as the jenkins user, revert back to root so that we can configure runit to monitor Jenkins.
First create a staging directory for runit configurations by executing the following command :
# mkdir -p /etc/runit/jenkins
Create a script named run in the new directory with the following contents:
#!/bin/sh -e
cd /opt/jenkins
exec 2>&1
exec chpst -u jenkins -e /etc/runit/jenkins/env java -jar jenkins.war
Now make the script executable.
# chmod +x /etc/runit/jenkins/run
Notice the -e /etc/runit/jenkins/env argument we are passing to chpst. We can use this directory to configure environment variables that will be set when executing our process.
Go ahead and create the env directory.
# mkdir /etc/runit/jenkins/env
We would like to explicitly define the JENKINS_HOME environment variable to control where Jenkins stores its data. To do this we need to create a file with the name of the environment variable in the env directory containing the value we would like it to set it to.
Define a value for the JENKINS_HOME variable by executing the following command:
# echo /opt/jenkins/.jenkins > /etc/runit/jenkins/env/JENKINS_HOME
This will instruct Jenkins to use /opt/jenkins/.jenkins as the home directory instead of the default. Before we continue, let's cleanup the files that Jenkins created in the default home location.
# rm -Rf /home/jenkins/.jenkins
The only thing left to do is configure logging for the service. First create the logging configuration by making a log sub directory under /ect/runit/jenkins.
# mkdir /etc/runit/jenkins/log
Next, create a script named run in the log directory with the following contents:
#!/bin/sh
exec chpst -u jenkins svlogd -tt /opt/jenkins/logs
Make the script executable.
# chmod +x /etc/runit/jenkins/log/run
The /opt/jenkins/logs directory does not exit, so create it and change its ownership to the jenkins user.
# mkdir /opt/jenkins/logs
# chown jenkins:jenkins /opt/jenkins/logs
That is all of the configuration that we need to address process management, logging, and defining environment variables. Go ahead and deploy the service by creating a symbolic link from the /etc/service/jenkins directory to our staging directory.
# ln -s /etc/runit/jenkins /etc/service/jenkins
If everything worked, you should see information being written to the logs and Jenkins should be available on port 8080. Please take some time to review the basics of runit if you are not clear on what we just setup.
Continuous Integration GO!!!
At this point you have everything you need to setup a monitored Jenkins server with logging. Your next step should be to read the Jenkins documentation to configure Jenkins to suit your needs. A good place to start is the "Use Jenkins" wiki.
https://wiki.jenkins-ci.org/display/JENKINS/Use+Jenkins
Contact Me
If you have any questions or would like further clarification, please feel free to shoot me an email. I would be glad to help.
Kevin