Ben Ramsey

Setting Up Jenkins on Amazon Linux for PHP Testing

"Coding Shots Annual Plan high res-5" by Matthew (WMF) - Own work. Licensed under Creative Commons Attribution-Share Alike 3.0 via Wikimedia Commons

One of my first tasks at ShootProof was to set up a Jenkins server for continuous integration and get it ready to run unit tests for PHP and JavaScript code. There are plenty of tutorials around the web to help you do just that. This is yet another one, but it’s primarily my cleaned-up notes—and less of a tutorial—placed here for my future self to find and provided publicly for all to benefit.

These instructions are specifically tailored for setting up Jenkins on an Amazon Linux EC2 instance. If that’s not what you’re running, your mileage may vary. These commands should run on RHEL-based systems, and with modifications to the package manager and names of packages, they should work on other Unix-like systems.

1. Launch and Prepare an EC2 Instance

The Amazon Linux AMI I used was the latest (at the time) paravirtual, 64-bit, instance store AMI (ami-ed8e9284), but choosing the latest for your region should work just fine. You can use an EBS-backed volume instead and set up regular snapshots of it, or you can follow these directions, create an AMI from your configured instance, and set up regular snapshots of the EBS volume we attach to the instance. Either way will work fine. I just happened to use an instance store with an EBS volume attached.

  1. Launch an EC2 instance (use this link to launch one, if you like)
  2. Create an EBS volume
  3. Attach the EBS volume to the instance you launched
  4. SSH to the instance, format and mount the EBS volume (see below)

I’m using XFS for the EBS volume’s file system, but you may use what you prefer. We’ll mount the volume at /var/lib/jenkins, so that we don’t have to do any complex trickery with the default jenkins user, home, and permissions. The EBS volume may exist at /dev/xvdf, as it does in the following example, or it may be attached at another point. See also Amazon’s guide to “Making an Amazon EBS Volume Available for Use.”

Note: All of these instructions require root access. You may prefix them with sudo, or you may change to the root user.

1
2
3
4
$ yum install xfsprogs
$ mkfs -t xfs /dev/xvdf
$ mkdir -p /var/lib/jenkins
$ mount /dev/xvdf /var/lib/jenkins

Now, the volume is mounted at /var/lib/jenkins. We want to ensure it always gets mounted there when we restart the instance, so let’s add a line to /etc/fstab:

1
2
3
$ cp /etc/fstab /etc/fstab.orig
$ sh -c 'echo "/dev/xvdf  /var/lib/jenkins  xfs  defaults,nofail  0  2" >> /etc/fstab'
$ mount -a

2. Install and Start Jenkins

Installing and starting Jenkins is fairly simple. We need to add the official Jenkins project repository to the list of yum repos, and then we install with yum, start the service, and ensure that Jenkins starts up on a reboot.

1
2
3
4
5
6
$ wget -O /etc/yum.repos.d/jenkins.repo http://pkg.jenkins-ci.org/redhat-stable/jenkins.repo
$ rpm --import http://pkg.jenkins-ci.org/redhat-stable/jenkins-ci.org.key
$ yum update
$ yum install jenkins
$ service jenkins start
$ chkconfig jenkins on

3. Configure the Server for Running Tests

Now, we need to install some stuff on the system so that Jenkins can do its thing. These instructions are intended for tests that use the Template for Jenkins Jobs for PHP Projects. This will give you a basic PHP installation with all the tools necessary to run the template. If you need to use anything that deviates from the stock template, then you’ll need to make changes.

1
2
3
4
$ yum install ant git graphviz gcc gcc-c++
$ yum install php55 php55-devel php55-common php55-cli php55-intl php55-gd php55-pecl-imagick php55-mbstring php55-mcrypt php55-mysqlnd php55-pdo php55-pecl-xdebug
$ sh -c 'sed -i "s/^memory_limit =.*/memory_limit = 256M/" /etc/php.ini'
$ sh -c 'sed -i "s/^;date\.timezone =.*/date\.timezone = America\/New_York/" /etc/php.ini'

Node.js

Since I want to use Node.js for various build tools and to run JavaScript tests, I installed Node.js from source (yum always seems to have an outdated package). If you don’t need Node.js, you may skip this.

1
2
3
4
5
6
7
$ wget http://nodejs.org/dist/v0.10.30/node-v0.10.30.tar.gz
$ tar zxf node-v0.10.30.tar.gz && cd node-v0.10.30
$ ./configure
$ make
$ make install
$ ln -s /usr/local/bin/node /usr/bin/node
$ ln -s /usr/local/bin/npm /usr/bin/npm

See those last two lines where I’m creating symlinks? This is because the jenkins user doesn’t have /usr/local/bin in its PATH. Rather than adjusting the user’s PATH, I chose to create symbolic links in /usr/bin, so that jenkins can find the node and npm programs.

PhantomJS and CasperJS

Finally, I also want to install PhantomJS and CasperJS to supplement and aid in my JavaScript testing. If you don’t need these, you may skip this.

1
2
3
4
5
6
7
$ yum install fontconfig freetype libfreetype.so.6 libfontconfig.so.1 libstdc++.so.6
$ wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2 --no-check-certificate
$ tar jxf phantomjs-1.9.7-linux-x86_64.tar.bz2
$ cp phantomjs-1.9.7-linux-x86_64/bin/phantomjs /usr/local/bin/phantomjs
$ npm install -g casperjs
$ ln -s /usr/local/bin/phantomjs /usr/bin/phantomjs
$ ln -s /usr/local/bin/casperjs /usr/bin/casperjs

Notice the symbolic links created in the last two lines again. This is for the same reason I mentioned earlier: to help the jenkins user find these programs in its PATH.

4. Configure Jenkins

Now, we’ve got Jenkins running, and the server has been configured to run our tests. You can go to Jenkins in a web browser to do the rest. By default, Jenkins runs on port 8080, so you can go to http://ec2-x-x-x-x.compute-1.amazonaws.com:8080/ to set it up.

The first thing you’ll want to do is enable security. I prefer to install the GitHub OAuth Plugin and use GitHub to authenticate with Jenkins. I would also recommend setting up a proxy to Jenkins through Apache or Nginx and installing an SSL certificate to encrypt your communications with Jenkins. You might also consider using AWS security groups to restrict access to Jenkins by IP addresses. All of these are outside the scope of this post.

  1. Install the Jenkins plugins required by the Template for Jenkins Jobs for PHP Projects. You’ll also need to install the required PHP tools listed on that page, or you may choose to use my jenkins-php meta-package with Composer to install them for you when you run Jenkins builds. If you choose the latter, be sure to set up your Ant build.xml script to also run composer install on each build during the “prepare” stage and point the executable for each tool to the vendor/bin/ directory (where Composer installs them).
  2. Create the Ant build.xml script for your project.
  3. Install the job template for PHP jobs and set up your first job using the template.

Here are a few other plugins that might come in handy:

  • GitHub Plugin: this plugin allows you to configure a job to pull source from a GitHub project, and you can set up GitHub web hooks to trigger builds on each code push to the repo
  • GitHub pull request builder plugin: this plugin will allow you to trigger a build on a pull request
  • HipChat Plugin / IRC Plugin / Slack Notification Plugin: these plugins allow you to configure a job to send messages to channels on your favorite team chat servers

Comments