Setting up a Jenkins server

This page contains instructions and a script for setting up a Jenkins Continuous Integration Server for automated building of all of the TEI products.

What is a Jenkins server?

The purpose of a Jenkins server is to watch a code repository waiting for changes in the code. When it detects a change (because someone has edited one of the source code files), it downloads the changes and starts building the codebase to create an updated version of the project, whatever that is. In the case of the TEI, there are five different sub-projects, each of which is built separately: the Roma schema-building tool, the TEI Stylesheets, TEI P5, TEI P5 Documentation (the Guidelines etc.), and some TEI P5 test cases.

Why would I want to create a Jenkins server?

A Jenkins server is useful to project administrators because it will automatically create new builds whenever the codebase changes, so the admins don't have to remember to do that themselves. It will also notify you when a build fails, perhaps because a recent change to the source contained an error. Programmers working on the codebase can use this feature to check the changes they have made to make sure they're OK, and roll them back if they don't work, without having to have a complete build environment set up on their own computers.

The TEI's main Jenkins server, in Oxford, is at http://tei.oucs.ox.ac.uk/jenkins/. There you can see the five build targets and look at their status -- when they were last built, when the last build failure occurred, etc. The Humanities Computing and Media Centre at the University of Victoria is in the process of setting up a second Jenkins server for the TEI. As soon as this is running, the URI will be included in this page. You might want to set up your own Jenkins server for a number of reasons:

• To add extra redundancy to the TEI project build process
• To add your own build targets for specific purposes
• To learn about Jenkins so that you can help administer one of the main servers

How do I go about creating a Jenkins server?

There are three stages:

1. Build a basic headless Ubuntu server, using the Ubuntu Lucid (Long-Term Support) edition.

2. Run our customization script to install all of the TEI and Jenkins code.

3. Make some final tweaks to your setup (adding an oXygen license and setting up security for Jenkins).

You will need to be comfortable with installing Linux and doing a couple of things at the command line. If you've never done this kind of thing before, this project is probably not for you.

Stage one

Download the latest distribution of the Ubuntu Lucid (10.04) server ISO from the Ubuntu download site (http://www.ubuntu.com/download/ubuntu/alternative-download).

Install the distribution on the machine you're going to use as your server (or on a virtual machine, if you don't have a piece of hardware to dedicate to the job). Choose "Internet server" when you're asked what type of computer you're setting up, during the install process. Then do all the updates to make sure your Lucid installation is fully updated.

Stage two

Download our script from here: [images/a/a5/Jenkins_builder_script.sh.zip http://wiki.tei-c.org/images/a/a5/Jenkins_builder_script.sh.zip]. Unzip it, and get the script onto your server somehow. Make it executable, and run it as root. You'll see some basic instructions as it starts up. Agree to all EULAs along the way. When the script completes, you should have a working Jenkins machine. The Jenkins GUI will be running on its default port of 8080, and if you connect to your server on that port, you should see it start to run the five TEI jobs. The first run takes a long time, because it has to download all the source code from SVN, but subsequent builds triggered by changes should be much quicker.

Stage three

First, make sure you add a valid oXygen license key file in the appropriate location, so that your use of oXygen on this machine is legal. Put your oXygen licence key in a file called licensekey.txt in the oXygen directory (/usr/share/oxygen/).

Next, set up some security for your Jenkins installation, by using the Jenkins management interface on port 8080 There are various ways to do this, using different authentication methods, but this is the simplest:

• Click on Manage Jenkins, then Configure System.
• Check "Enable security".
• Choose "Jenkins's own user database".
• Choose "Matrix-based security".
• Create a new user (called, for instance, "tei"), and give it full privileges (check everything for that user).
• For the Anonymous user, check only the Read boxes in Overall and Job.

Now log in as the new user ("tei") and set a password for yourself. Now anyone can see the progress of jobs, but only the tei user can log in and make changes.