Installing Jenkins for Use with TeamForge

This week I was working with a customer, helping to set up a sandbox environment for them, including helping them to build a local Jenkins server to use with TeamForge.  I’ve done this a few times now, but every time I end up back in the same places, figuring out the same things over again so this time, I’m going to document it for me, and for you.  There’s a pretty good chance, I think, that I’ll end up doing this again for a proof of concept with a prospective customer one day, so having this information handy will be… handy.  Are you ready?  Let’s dive in.

The Basic Setup

This Jenkins server will run in a local VMware image to do Maven and Ant builds with source from Git and Subversion.  It will be used by a TeamForge project in CollabNet’s TrialZone, as well as possibly others.  The server itself is running CentOS 7.  Since it will be used by TeamForge and Orchestrate, the necessary plugins will be installed for TeamForge and Orchestrate (which has to come from collab.net).  I like Jenkins to show up in an iFrame in TeamForge, so we’ll want to enable that access with the Jenkins plugin for XFrame filtering, too.  Lastly, so that Jenkins will display nicely within the TeamForge web client and for security, Jenkins will be set up to use HTTPS.  This guide assumes that you have already downloaded the CentOS 7 full installation DVD and have created a new, empty VM (either with VMware or VirtualBox) and installed CentOS 7 into it.

Server Preparation

Jenkins works best if the server is named something other than localhost.localdomain, so one of the first things we’ll do is change the hostname using the hostnamectl command:

hostnamectl set-hostname buildbox.demo

systemctl restart systemd-hostnamed

The next thing to do is to make sure that name resolution works from within the host as well, so I had to put the name and alias in /etc/hosts as well as setting the hostname above.

So that Jenkins is available outside of the server, the 8080 and 8443 ports that Jenkins will use need to be opened up in the firewall:

firewall-cmd --zone=public --add-port=8080/tcp --permanent

firewall-cmd --zone=public --add-service=http -–permanent

firewall-cmd --zone=public --add-port=8443/tcp --permanent

firewall-cmd --zone=public --add-service=https --permanent

firewall-cmd –-reload

Installing Jenkins

There are several ways to install Jenkins.  The easiest is just to download the package from Jenkins-ci.org, unzip it and run it, but this doesn’t set up any of the start up scripts.  I prefer install Jenkins using yum because the Jenkins package sets up the necessary script in /etc/init.d and the proper sym links in /etc/rc*.d.  Before Jenkins can be installed, it needs to be downloaded.  Download it by issuing the following command:

sudo wget -O /etc/yum.repos.d/jenkins.repo http://pkg.jenkins-ci.org/redhat/jenkins.repo

The system will respond with something like:

--2015-05-15 08:04:32--  http://pkg.jenkins-ci.org/redhat/jenkins.repo  Resolving pkg.jenkins-ci.org (pkg.jenkins-ci.org)... 199.193.196.24

Connecting to pkg.jenkins-ci.org (pkg.jenkins-ci.org)|199.193.196.24|:80... connected.

HTTP request sent, awaiting response... 200 OK

Length: 75 [text/plain]

Saving to: ‘/etc/yum.repos.d/jenkins.repo’

100%[======================================>] 75          --.-K/s   in 0s

2015-05-15 08:04:32 (15.5 MB/s) - ‘/etc/yum.repos.d/jenkins.repo’ saved [75/75]

Import the package to the redhat package manager and install it with yum using these two commands:

 rpm --import http://pkg.jenkins-ci.org/redhat/jenkins-ci.org.key

yum install Jenkins

Start Jenkins using the CentOS service command:

service jenkins start

And the system should respond with something like:

 Starting jenkins (via systemctl):                          [  OK  ]

By default, Jenkins answers on port 8080, so you can verify Jenkins is working by pointing your browser to http://:8080/  and Jenkins should respond.

Integrating Jenkins into TeamForge

Most of what’s needed to integrate Jenkins into TeamForge is done from the TeamForge Project Admin tab, but I like Jenkins to appear in an iFrame within TeamForge because I think it looks more integrated that way.  To be successful with this, Jenkins needs to be using HTTPS, so there are a few steps to take in Jenkins to make that happen:

Jenkins HTTPS

You need to tell Jenkins what port to use for HTTPS, as well as where the certificate lives, and of course, create a certificate if you don’t have one from a dedicated Certificate Authority (CA).  Start by editing the Jenkins config file:

vi /etc/sysconfig/jenkins

Change the following parameters in the config file (note they go in quotes in the file):

Parameter	Value
JENKINS_PORT	-1
JENKINS_HTTPS_PORT	8443
JENKINS_HTTPS_KEYSTORE	/usr/lib/jenkins/keystore
JENKINS_HTTPS_KEYSTORE_PASSWORD	P@ssw0rd

Note that the path to the keystore and the password are the examples from my system.  Feel free to use them, or change them to meet your needs, but they work with the following command that creates the keystore.

keytool -genkeypair -keyalg RSA -dname "cn=Steve Grossman, ou=Texsas, o=Collabnet, c=US" -keypass P@ssw0rd -keystore /usr/lib/jenkins/keystore -storepass P@ssw0rd -validity 720

This command creates a key pair and puts it in /usr/lib/jenkins/keystore with the password P@ssw0rd, good for 2 years.  You should, of course, change the options for –dname to something that makes sense for your installation.

Restart Jenkins

systemctl restart jenkins

Jenkins should now be using HTTPS.  Verify this by pointing your browser to https://:8443/

Install Jenkins Plugins

This is really the easy part and is, with the exception of the TeamForge Orchestrate plugin, just a matter of clicking the mouse.  Point the web browser to your Jenkins URL, click on the Manage Jenkins link on the left navigation bar, and then click the Manage Plugins link.

Click on the Available tab, select the following plugins.  There are a lot of Jenkins plugins, so using the Filter capability in the upper right corner of the page will make it easier to find the needed plugins:

• XFrame Filter Plugin
• Subversion Plug-in
• Maven Integration plugin
• Git plugin
• CollabNet Plugins
• Ant Plugin

After the plugins have been selected, click the “Download now and install after restart” button at the bottom of the page.  Restart Jenkins using systemctl as above.

Download the TeamForge Orchestrate Jenkins plugin from https://orchestrate.help.collab.net/entries/24752123-Jenkins-Adapter.  The download will most likely show up as a garbled webpage, just right mouse on the page, use Save Page As and save it as a .hpi file on your server.

The installation instructions are at http://help.collab.net/index.jsp?topic=/Orchestrate_ditamap/faq/jenkins_overview.html, but the installation is very easy.  In the Jenkins Plugin Manager page, select the Advanced tab and in the middle of the Advanced page browse to the .hpi file downloaded above and upload it into Jenkins, then restart Jenkins.

Configure Jenkins Plugins

Most of the plugins don’t require any configuration, but the XFrame Filter and the Orchestrate do require some configuration.  On the top level Jenkins page, click the Manage Jenkins link on the left navigation bar and then select the Configure System link.  Scroll down to the XFrame Filter Configuration section, select “Send X-Frame-Options HTTP Header” and enter ALLOW-FROM https://trialzone.collab.net (substitute your server name) in the X-Frame-Options Options field.

Setting up Jenkins for a TeamForge project

Once all of the above steps are completed, you’re ready to set up Jenkins with your TeamForge project.  Assuming you have project admin rights on the project, click on the Project Admin tab in the TeamForge web client, and then select Build and Test Integration from the Project Admin navigation menu on the left side.  Enter the URL for your Jenkins server, select to have it open in an Iframe, and enable single sign on:

After taking these steps, clicking on the Build & Test tab in the TeamForge web client, Jenkins will display neatly on the tab.  If you just have one build job for the project, you can always specify the Override URL (above) as a link into that build job.

 

Once you have Jenkins set up in this way, it’s integrated with TeamForge and you can set up your Jenkins jobs to pull in new commits into your Git or Subversion repositories, perform code reviews using Gerrit or Review board, deploy the results of those builds into the TeamForge File Releases area or the Nexus binary repository while TeamForge Orchestrate captures the traceability between all of those activities so you can ensure your best practices and required processes are being followed.  In a subsequent blog, I’ll cover briefly how to set up a Jenkins job to use these capabilities, including using TeamForge to manage the access to Jenkins.