Guide to Integrating Rational Build Forge with IBM SmartCloud Continuous Delivery

Forest Huo, IBM
Last updated: November 8, 2012
Build basis: Build Forge 7.1.3.3 and IBM SmartCloud Continuous Delivery 2.0

By default, IBM SmartCloud Continuous Delivery uses the Jazz Build Engine to run continuous delivery builds. However, Rational Build Forge offers several improvements over the Jazz Build Engine, such as distributed builds, improved performance, and more powerful organization and management of your builds. The following table shows a more detailed comparison of Build Forge and the Jazz Build Engine:

Jazz Build Engine – simple build toolkit

Build Forge – enterprise continuous delivery engine

Lightweight definitions Build definition Build engine declarations Data model for build results Logs, downloads, links, compile/test Information Traceability to work Items and code Build toolkit In the form of Ant tasks Build engine Simple build engine Continuous integration loop

Distributed capability Simultaneous execution on many platforms Broader platform support Distributed purge and clean-up Improved capacity and throughput Ability to parallelize and accelerate process execution Ability to manage highly varied toolsets without scripting Governance and traceability across tools and machines Integrated scheduler for non-compile related tasks Sophisticated logging of whole build output Integrated security Ability to manage processes for Jazz and non-Jazz environments simultaneously Process automation, not just build automation (process automation is a superset of build automation)

This article provides a step-by-step example of how to set up a continuous delivery environment with Rational Build Forge and Smart Cloud Continuous Delivery.

The following diagram shows the components of a continuous delivery pipeline that includes Rational Build Forge. Note that the Jazz Build Engine is still part of the solution, because the Build Forge server manages one or more Jazz Build Engines. Each build starts with the Rational Team Concert server, which sends the build request to the Build Forge server. The Build Forge server then sends the build request to a Jazz Build Engine.

---

Integration Process Overview

As above image shown, there are 4 phases in a continuous delivery build:

1. Build: Build and package the application and infrastructure
2. Publish: Publish the application, infrastructure, and manifest to the library server (Rational Asset Manager)
3. Deploy: Invoke the assets from the library server to deploy the application
4. Validate: Ensure that the application and platform are behaving as expected through automated tests

---

Prerequisites

To follow this article, you must have installed IBM SmartCloud Continuous Delivery. This system includes the following components:

• A cloud host, such as IBM Workload Deployer, IBM SmartCloud Provisioning, or IBM PureApplication System
• An installation of IBM Rational Team Concert
• A library server, which includes a customized instance of IBM Rational Asset Manager
• A dependency server
• A Rational Team Concert client with the SmartCloud Continuous Delivery extensions
• One or more build engines

For installation instructions, see the SmartCloud Continuous Delivery information center link in the Reference section.

---

Import the sample application

SmartCloud Continuous Delivery includes a sample application that you can use to set up an example continuous delivery build. It also includes example continuous delivery projects for the application. This article focuses on this application, so you can try the sample first and then set up builds for your own applications.

Instructions for downloading and importing the sample application are available in the information center (see the link in the Reference section). In general, you download an archive file that contains the projects in the sample application, import these projects into the Rational Team Concert client, and check these projects into the Rational Team Concert server. For complete instructions, open the SmartCloud Continuous Delivery information center and click Samples > Sample application for IBM SmartCloud Continuous Delivery > Installation Instructions for the sample application > Loading the sample application.

---

Import the Build Forge sample project

Similarly, you must download the sample Build Forge project and import it to the client. Please refer the download link in the Reference section of this article to download this project. This project contains the following artifacts:

• build.properties: This file contains the properties that will be used in the build, such as credentials and server locations
• buildApplication.xml: This Ant script contains the instructions for the build phase
• publishAsset.xml: This Ant script contains the instructions for publishing assets to the library server
• deployApplication.xml: This Ant script contains the instructions for deploying the application to the cloud host
• SCCD_Integration_Project.xml: This Build Forge project invokes the Ant scripts

The following figure shows the project in the Rational Team Concert Client:

---

Configure the environment

The following servers need to be set up for the integration:

• Rational Team Concert Server (4.0 or above)
• Rational Asset Manager (also known as the library server)
• Build Forge Server (7.1.3.3 or above)
• Build Engine (with Jazz Build Engine and Build Forge Agent installed)

SmartCloud Continuous Delivery uses a customized Jazz Build Engine. You cannot use an unmodified Jazz Build Engine with SmartCloud Continuous Delivery. To install the build engine, see the topic “Configuring build engines for continuous delivery” in the SmartCloud Continuous Delivery help.

After you configure the build engine for continuous delivery as described in the information center, configure the build engine with the following steps:

1. Install the Rational Build Forge Agent.
2. Ensure that Apache Ant version 1.7.1 is installed to the folder /opt/apache-ant . (The SmartCloud Continuous Delivery build engine installer installs this software automatically.)
3. Ensure that the ant-contrib library JAR file, such as ant-contrib-1.0b3.jar, is installed to the folder /opt/ant-contrib . (The SmartCloud Continuous Delivery build engine installer installs this software automatically.)
4. Install the Rational Asset Manager client to the folder /opt/ramclient.
5. From the Build Forge sample project, copy the JAR files in the folder lib/devops-ant-tasks to the build engine, in the folder /opt/devops-ant-tasks.

Integrating the components

Configure the Build Forge Server

In this section, we put the Build Forge sample project on the server and modify environment variables to fit your environment.

1. Log in to the Build Forge web console.
2. Go to Administration > Import and import the sample project into Build Forge.
3. Go to Projects, click the SCCD Integration Project to see its steps. Click deploy application step and change the buildDefinitionId property value to your SmartCloud Continuous Delivery build definition which response to deploy the application to the Cloud. At this step, Build Forge will pass the manifestVersion to the build definition, then the build definition will get the application from Rational Asset Manager base on the manifestVersion and deploy it to the Could, at last, the build definition will auto run a test to verify the deployment is success.
4. Go to Environments, open the environment named SCCD_Integration_Environment, and specify the following environment variables:

Environment variable	Value
buildUser	The ID of the build user on the Rational Team Concert server
buildPassword	The password for the build user on the Rational Team Concert server
buildEnginePath	The Jazz Build Engine install path, usually /opt/ibm/rtc_build
repositoryAddress	The address of the Rational Team Concert server, for example: https://<repository URL>:9443/ccm/
engineId	The Jazz Build Engine ID

Configure the Rational Team Concert Server

In this section, we set up the Rational Team Concert Server, which sends build requests to Build Forge and displays the build results from Build Forge. You must create two build engine definitions: one for the Build Forge server and one for the Jazz Build Engine. These definitions can use the same physical build engine machine.

1. Connect the client to the Rational Team Concert server.
2. Make sure that you are using the project area for the sample application and that you have all of the projects for the sample application loaded in your local workspace. Your workspace should look like the following picture:
3. Create a Jazz Build Engine definition with the ID jazz-sccd-engine using the following steps. This engine loads the application source code for Build Forge to build.
   1. In the Rational Team Concert client, go to the Team Artifacts view and expand your project area and the Builds folder.
   2. Right-click the Build Engines folder and then click New Build Engine.
   3. Click Create a new build engine and then click Next.
   4. In the ID field, specify the following ID: jazz-sccd-engine
   5. Under Available build engine types, click Jazz Build Engine, and then click Finish.
   6. Fill in the information for your build engine and save the build engine definition.
4. Similarly, create a Build Forge build engine definition with the ID bf-sccd-engine: This engine will connect to Build Forge and will be used by the bf-sccd-integration build definition to process the build, publish the resulting artifacts, and deploy the application. It can share the same build engine machine with jazz-sccd-engine. We will create this build definition in the next step.
   1. In the Rational Team Concert client, go to the Team Artifacts view and expand your project area and the Builds folder.
   2. b. Right-click the Build Engines folder and then click New Build Engine.
   3. Click Create a new build engine and then click Next.
   4. In the ID field, specify the following ID: bf-sccd-engine.
   5. Under Available build engine types, click Rational Build Forge, and then click Finish.
   6. Fill in the information for your build engine and save the build engine definition. The Build Forge build engine definition looks like the following picture:
5. Create a build definition named bf-sccd-integration with the Rational Build Forge Template:
   1. In the Team Artifacts view, right-click the Builds folder and then click New Build Definition.
   2. Click Create a new build and then click Next.
   3. Specify the following ID: bf-sccd-integration.
   4. Under Available build templates, select Rational Build Forge and click Next.
   5. Select the Jazz Source Control check box and then click Finish.
6. In the new build definition, on the Overview tab, add bf-sccd-engine to the Supporting Build Engines list, as shown in the following picture:
7. On the Build Forge tab, click Get Projects to get the SCCD_Integration_Project.xml Build Forge project.
8. Click Synchronize Properties to synchronize properties between the Rational Team Concert server and the Build Forge server, as shown in the following picture:
9. On the Jazz Source Control tab, specify the workspace for the build. The build user must own this workspace. For more information, see the topic “Creating a build definition and workspace for applications” in the SmartCloud Continuous Delivery information center.
10. Under Load Options, set the load directory to “/etc/bf/work”, as shown in the following picture. At build time, the build engine loads the application source code into this directory.

Configure the build engine

In this section we set up the build engine machine, which runs the builds.

1. Log in to the build engine machine and create a “/etc/bf/jobworkspace/scripts” directory.
2. From the com.ibm.devops.sample.buildforge sample project, copy the following files to the new directory: buildApplication.xml, publishAsset.xml, deployApplication.xml and build.properties.
3. Update the build.properties file based on the host names and passwords to fit your environment.

---

Run a build

To request a build and run the integration, open the bf-sccd-integration build definition and click Request Build. To check that the build is running, you can open the web console for the Build Forge server and click Jobs > Running. The build is also shown in the Rational Team Concert client, in the Builds view. When the build is finished, open the Builds view, double-click the build result, and go to the Activities tab. This tab shows the build and publish results, as shown in the following example:

Also in the Ration Team Concert client, double click the SmartCloud Continuous Delivery build definition, in the Builds View, you will see a new build of the build definition is triggered, after the build finished, you can check the deployment result, as shown in the following example:

---

Reference

• Build Forge sample project
• SmartCloud Continuous Delivery information center
• Build Forge information center
• Rational Team Concert information center
• Rational Asset Manager information center

---

About the author

Forest Huo is a developer of IBM Build Forge Team. He works for IBM in China Development Lab. Beijing. He can be contacted at huozz@cn.ibm.com.

Copyright © 2012 IBM Corporation