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.
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
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)... 188.8.131.52
Connecting to pkg.jenkins-ci.org (pkg.jenkins-ci.org)|184.108.40.206|: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://<yourhostname>: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:
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:
Change the following parameters in the config file (note they go in quotes in the file):
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.
systemctl restart jenkins
Jenkins should now be using HTTPS. Verify this by pointing your browser to https://<yourhost>: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.