OpenShift offers one-click attachment of a Jenkins instance to your application. When created in this way from within an application’s dashboard, it will be automatically configured to deploy changes pushed to your gear’s git repository.

Enable the Jenkins cartridge

1. Go to the dashboard for the app you’d like to add Jenkins to within the OpenShift Online Console.

2. Under “Continuous Integration” click the “Enable Jenkins” link.

   

3. On the next page either leave the default application name of jenkins (so your Jenkins URL will be http://jenkins.yoursitename.rhcloud.com/) or name it something else. Click the “Add Jenkins” button to install the new gear and link it with your application.

   

4. On the next page note the user credentials for the Jenkins instance, then navigate to the “appname-build” job page on Jenkins at https://jenkins.yoursitename.rhcloud.com/job/appname-build/.

   

Pushing changes and triggering a build

1. Push code changes to your application’s repo on OpenShift as you normally would. Rather than seeing the deploy process in your console you should see “Executing Jenkins Build” and the build status. Jenkins will create a temporary “builder application” called “appnamebldr” for executing the build (more info) which will be deleted after 15 idle minutes.
2. Scan through the console output of the build to see that all went well. If the Jenkins build status is SUCCESS at the bottom your updated application code should be deployed to your gear.

Triggering builds remotely

You may want to kick off Jenkins builds from the command line:

1. Go to your project dashboard in Jenkins and click “Configure”

2. Scroll down to “Build Triggers” and check “Trigger builds remotely (e.g., from scripts)”

   

3. Add an authentication token (any string, generate something with 1Password perhaps) and click “Save”

4. Click “Jenkins Admin” in the header then “Configure” access the settings for the builder account. Click the “Show API Token” button to get the credentials you need for the request:

   

5. You can now trigger a build with a POST request using curl for example:

   curl -X POST https://USERNAME:[email protected]_URL/job/JOB_NAME/build?token=AUTH_TOKEN

Note: Alternatively you may wish to trigger this build by using Node to run a script like this one, use the official Jenkins CLI tool or even trigger the build via email.

Retrying failed builds

I’ve found the first build often fails due to the builder application not having completed booting up yet (it powers down after 15 minutes of inactivity). For this reason I use the Jenkins Startup Trigger plugin to ensure the build starts when the builder application does.

1. Navigate to Manage Jenkins > Manage Plugins and click the “Advanced” tab. Then click the “Check now” button at the bottom of the page to check for the latest plugin updates.

   

2. Click the “Available” tab and search for the “Startup Trigger” plugin. Install this.

3. In your project’s settings you’ll now have “Build when job nodes start” as a “Build Triggers” option. Enable this and fill in the name of the builder application e.g. “productionbldr”. This will trigger builds when this builder application starts, rather than when the master Jenkins instance starts which is the default.

   

Purging CloudFlare cache

If you’re using CloudFlare in front of your website you may want to purge the cache after your code has deployed as part of the build script. In these instructions we’ll fetch the CloudFlare Zone ID for your domain and use it in a curl command to purge the domain’s CloudFlare cache.

1. Get your “Global API Key” from your CloudFlare account settings page.

   

2. Get your domain’s “Zone ID” by running the following curl command:

   curl -X GET "https://api.cloudflare.com/client/v4/zones?name=yourdomain.com&status=active&page=1&per_page=20&order=status&direction=desc&match=all" \
    -H "X-Auth-Email: [email protected]" \
    -H "X-Auth-Key: <global-api-key>" \
    -H "Content-Type: application/json"

3. Copy the “id” value from the response (this is your domain’s Zone ID) and use it in the following curl command to purge your domain’s cache:

    curl -X DELETE "https://api.cloudflare.com/client/v4/zones/<zone-id>/purge_cache" \
    -H "X-Auth-Email: [email protected]" \
    -H "X-Auth-Key: <global-api-key>" \
    -H "Content-Type: application/json" \
    --data '{"purge_everything":true}'

   See CloudFlare’s documentation for this

4. I set these credentials as Jenkins environment variables at Manage Jenkins > Configure System > Global properties:

    CLOUDFLARE_ZONE_ID
    CLOUDFLARE_AUTH_EMAIL
    CLOUDFLARE_AUTH_KEY

5. Then you can add the final command to the end of your deployment script in the project’s settings:

    curl -X DELETE "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
    -H "X-Auth-Email: ${CLOUDFLARE_AUTH_EMAIL}" \
    -H "X-Auth-Key: ${CLOUDFLARE_AUTH_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"purge_everything":true}'

Note: An alternative would be to enable CloudFlare’s “Dev Mode” before the deploy and disable it after the deploy.

Also worth noting:

• Configure Jenkins main settings at https://jenkins-yoursitename.rhcloud.com/configure
• Configure the Jenkins user account at https://jenkins-yoursitename.rhcloud.com/me/configure
• You can tail your Jenkins logs with rhc tail jenkins -n <namespace>
• You can view and manage Jenkins build with the iPhone app iJenkins