Setting up a Jenkins Template for Drupal Testing (CI on a Budget, part 2)

This post is part of my "Continuous Integration on a Budget" series, and covers setting up a Jenkins Template for Drupal Testing on a Jenkins CI server which, in this series, is set up on a Linode instance running Debian 7

In my previous post, I walked you through setting up a Jenkins CI server on a Linode instance running Debian 7. Here, we'll continue with configuring Jenkins with a job template that has been customized to work with a build template (which we'll cover also) to make testing Drupal sites under development relatively simple and painless. This post assumes you have a Jenkins CI server set up (as covered in this post).

The Jenkins Job Template for Drupal Projects

As you know, Drupal has a vast and very supportive community of site builders, developers and themers that are actively involved in making Drupal one of the most popular CMS installations today. I fully support walking in the footsteps of giants when it comes to rapidly implementing new processes, and leveraging the trials and experience of others who are willing to share those with us.

Continuous Integration, Automated Testing and Drupal is no exception.

The fine folks at Reload! out of Copenhagen, Denmark are part of that community, and have graciously made available in the public domain some templates that will help you get started on your quest for the Holy Grail. You can read more about this project at http://reload.github.io/jenkins-drupal-template/. The Reload! folks, in turn, built their contributions on the fine work done by Sebastian Bergman, who published to the PHP community a Template for Jenkins Jobs for for PHP projects.

Installing the Jenkins Template for Drupal Testing on your server

To install the template, shell into your Jenkins server. At the command line, use "su" to change over to the Jenkins user:

su (enter root password at the prompt)
su jenkins

Change your directory to "jobs" directory located in the "jenkins" user home directory:

cd ~/jobs #which will be /var/lib/jenkins/jobs if you took the package manager installation route

Clone the jenkins Template for Drupal Testing from the GitHub:

git clone git://github.com/reload/jenkins-drupal-template.git drupal-template

Reload Jenkins

exit (changes you back to the root user
service jenkins force-reload #or service jenkins restart

Go to your Jenkins server on the web (http://www.example.com:8080) and you should see a job titled "drupal-template" available, with a "gray" status indicator to the left of it.

Edit the drupal-template file, and expand the "Advanced Project" options. Add a placeholder here that points to a non-existent website in your webroot folder (For my example, we'll use "/var/public/_JenkinsDrupal2_.example.com//public_html"

Setting up your first Drupal Project for Jenkins

Ok, that was step one. You won't have to do that step again, but this step and the subsequent steps you will need to do for every Drupal project for which you wish to leverage Jenkins for automated builds using the Phing Drupal Template.

Step 1: Create a fresh Drupal install on your development instance

Create a fresh Drupal install in your development environment, just as you would if you were starting a new project. While you're at it, grab a contrib module (for this example we're going to use the Token module).

Step 2: Shell into your Jenkins server and create a database, username and password for this project

This will be the database, username and password that Jenkins will use along with your Phing Drupal Template to build your testing environment. Make a note of the database, username and password.

Step 3: Create a directory called "build" in the root of your Drupal installation

This directory will house two files, an XML file with phing build instructions, and a build default properties file housing some template defaults, some of which will be overridden on a project by project basis with another build properties file.

Step 4: Download the "build.xml" and "build.default.properties" files from my GitHub repository

These are slightly modified copies of the phing template and properties files originally created by Reload!, available at https://github.com/reload/phing-drupal-template. I cleaned some dirty characters, and added a couple of lines for building a working drupal site install via Jenkins, which we'll cover momentarily.

Place these two files in the "build" folder of your drupal project.

Step 5: Download the "build.properties" file from my GitHub repository into your Drupal root installation

This file contains the overrides for the build properties contained in the build.default.properties file in your "build" directory. Edit this file and replace the blank or default values with the following:

Line 2: replace "_DrupalJenkinsDemo_" with "demo-d7" (make a note of this, you will use it later).
Line 10: add a valid email address for the drupal superadmin account for your drupal admin superuser account that will be created when you build your test environment.
LIne 11: add a username for the drupal superadmin account from line 10
Line 12: add a password for the drupal superadmin account from line 10
Line 15: add the sitename you want configured on your test environment site. Enclose in double quotes ("") if you have spaces in the sitename
Line 16: add the site email address you want configured (can be the same as the email from line 10)
Line 20: change the drupal.uri to a subdomain on your Jenkins test server where you want the test environment to exist. I suggest using the project name from line 2 (i.e., http://demo-d7.example.com)
Line 36: Replace the placeholder drupal database URI with one using the database name, username and password from step 2, in the format of "mysql://username:password@localhost/databasename"
Line 30: uncomment this line, and add "Token" as the project.code.prefix. When we launch our Jenkins build, the automated tests for the Token module will automatically be run.

Save these changes.

Commit your code to a git repository (I use BitBucket for mine).

Creating your Jenkins Project for Drupal demo build

Back to Jenkins!

Step 1: Create an Apache Virtual Host file for your test build, and reload Apache

Shell into your Jenkins server and create an Apache Virtual Host file for your test build in /etc/apache2/sites-available (you will need to create this as "sudo" or "root"). Suggestion: Use the project name from line 2 of your build.properties file as the subdomain. Save this file.

Step 2: Set up your physical directories as specified in your Apache Virtual Host file

Set up a physical project directory on your server's hard drive that maps to the root directory of the virtual host you set up in Step 1. Change the ownership of that directory to the jenkins owner, and the jenkins group. This will allow Jenkins to clone your git repository, create test builds, and write test results to this location.

Step 3: Enable your virtual host

Enable the new virtual host file using "sudo a2ensite ", then "sudo service apache2 reload" or "sudo service apache2 restart".

Step 4: Log into Jenkins and create your project job

  • Log into Jenkins, and Click "New Item"
  • Name your project "demo-d7"
  • Select "Copy existing item", and enter "drupal-template", and click "OK"
  • click "Advanced Project Options" check "Use Custom Workspace", and specify the Custom Workspace Directory as the physical project directory created in Step 2, which matches the location specified in your Apache Virtual Host file from Step 1..
  • Under Source Code Management, select "Git", enter the URI of your git repository to use for cloning, and select the credentials you configured for your online git repo (GitHub or BitBucket) when you intitially set up your Jenkins install from the drop down presented.
  • Click "Save"

Step 5: Build your Project

On the left hand side of your screen, click "Build Now" from the sidebar column.

You should see an item appear in the "Build History" column, with a flashing blue ball, a progress bar, and a date time stamp of the build start time momentarily. If everything is configured properly, you should get a successful test build in approximately 3-5 minutes, depending on bandwidth and CPU processing availability.

If, for some reason, your build fails, browse through the "Console Output" of the "Build history", review any points of failure (you will have messages that will provide clues as to why your build failed), and start addressing the failures. Once you get them fixed, build again, rinse and repeat until you get a successful build.

Go forth, and test!