BuildForge Introduction

Before you start

About this tutorial

In this tutorial, learn how to install and configure IBM Rational® Build Forge® to build the open source project Jakarta Tomcat. Create a continuous integration environment for Tomcat, with builds occurring whenever changes are committed to the Tomcat Subversion repository. With this 2-part series, go from zero to 96 bpd (builds per day) in two days. This tutorial covers the tasks for the first day.

If you are a developer involved in build automation, or a system operator providing infrastructure support for build and deploy functions, this series is for you.

Part 2 (the second day) of this series describes how Build Forge provides for the reuse of existing project scripting. It also covers how Build Forge can extend a simple compile and package build process by adding customization and deployment capability.

Objectives

After completing this tutorial you will know:

• Basic Build Forge concepts
• How to install and set up Rational Forge
• How to create Build Forge objects to represent build servers for the tutorial
• How to configure a Hello World project to run

Prerequisites

It is assumed that you have some understanding of building applications based on Java™ technology. Build Forge is language agnostic, but the Tomcat project is written in the Java programming language. Experience with Apache Ant and Subversion is helpful, but not required.

System requirements

To complete the steps in this tutorial, you should have access to the following tools, which you can get by using the contact information on the Rational Build Forge product overview

Introduction This tutorial uses Tomcat as an example project to show how a Rational Build Forge implementation reuses existing scripts. Think of Tomcat as an analogy for any project you'd like to include in a build management system where you can't, or don't want to, change build scripts. In the tutorial example, Tomcat could represent any internal or external project related to your projects. Interrelated projects need to be deployed into an integration environment so they can be tested together. Triggering builds in the integration environment continuously when project codebases change (continuous integration), then running automated tests, is best practice for ensuring that system integration points continue working. When implementing build management, you want to avoid impacting developers' current build workflows, or limiting their future ability to innovate. Using an open source project is perfect. A build management system should be judged on: enabling an organization to achieve continuous integration, customized notifications, secure access, scheduling, and reporting without requiring development changes. The open source project will show how Rational Build Forge can automate the key tasks. Before and after

Install and set up Rational Build Forge

This section explains how to set up the required server components, as shown below.

For this tutorial, all server processes, including the database, will be running on a single host.

Install Rational License Server v7.0 Windows

The Build Forge Management Console will check for a valid license on startup. You need to install the Rational License Server and import an evaluation license before installing the Build Forge Management Console.

1. Unzip the installation files.
2. Run Setup. Select Install Rational License Server.
3. Accept the default options for the rest of the license server installation. When setup is complete, click Finish.

Import the Build Forge evaluation licenses into the license server

1. Start the License Key Administrator by selecting All Programs > IBM Rational > IBM Rational License Key Administrator.
2. Select Import a Rational License File, and click Next.
3. Browse to the location of the Evaluation License Key file.
4. Open the file, and click Import.
5. Verify that the licenses are valid, and click Import.
6. Agree to restart the license server.

Install MySQL 5.0.45

The Build Forge Management Console will store configuration data and build log files in a database. For this tutorial, install MySQL version 5.0.45.

1. Unzip the installation file, then run it.
2. When prompted, select the Complete setup.
3. Select Install.
4. Click Next until you see the window below. Select Configure the MySQL Server now, then click Finish.
5. Click Next, select the Standard Configuration, and click Next.
6. Select:
   • Install As Windows Service
   • MySQL for the Service Name
   • Launch the MySQL Server Automatically
   • Include Bin Directory in Windows PATH
   and click Next. 
7. Enter a root password, click Next, then click Execute.
8. Click Finish.

Create a MySQL database instance for Build Forge data

You need to create a database instance inside MySQL to store Build Forge data. You also need to create a MySQL user for Build Forge to connect with.

1. Open a command prompt and, as shown below, enter mysql -uroot -p<password entered during mysql install>
2. At the mysql prompt, enter create database build;
3. At the mysql prompt, enter grant all on build.* to build identified by 'build';
4. At the mysql prompt, enter quit

Install the Build Forge Management Console

Now that there is a license server ready to serve valid Build Forge licenses, and a database available and configured, proceed with the installation of the Build Forge Management Console.

1. Unzip the installation file, and run it.
2. Click Next on the setup wizard Welcome panel.
3. Select your destination folder.
4. Enter localhost for the License Host, and accept the default Http Server Port unless the system you are using is currently using that port (for example, another Web Server).
5. Enter MC1 for Location Name. Select Connect to existing database, and:
   • DB Name: build
   • DB Type: MySQL
   • DB Host: localhost
   • Username: build
   • Password: build
    
6. Click Install.
   After installation, the Build Forge Management Console will start up in the background as a service. When it starts and encounters the empty MySQL database, it will begin creating a table structure. This process may take a minute. Wait for the system to become idle before proceeding.
7. After stopping the Build Forge service (bfengine), you'll copy libmySQL.dll to the BuildForge Apache directory. At a command prompt, enter net stop bfengine
8. Enter copy "c:\Program Files\MySQL\MySQL Server 5.0\bin\libmySQL.dll" "c:\Program Files\BuildForge\Apache\bin"
9. Restart the Build Forge service by entering net start bfengine
10. Close the command prompt window.
11. Double-click the Management Console icon on the desktop.
12. Enter the User name root and Password root, and click Login.
13. You should then see the Management Console home page for the root user.
    

Install the Rational Build Forge Agent

Build Forge Agents can be installed on any system that will take part in a build, deploy, and test process managed by Build Forge. For this tutorial, install the agent on the same system as the Management Console. The agent system can, and usually will, be remote.

1. Unzip the installation file and run win-bfagent-7.0.1.211.exe.
2. Accept all defaults throughout the agent installation panels.
3. Click Finish when prompted.

This concludes the installation required for the Rational License Server, MySQL, the Rational Build Forge Management Console, and the Rational Build Forge Agent. The next section explains how to configure Build Forge to create a build process.

First steps to Hello World

In this section you create Build Forge objects to represent build servers for the tutorial, and configure a Hello World project to run. For a complete explanation of the options in these steps, see the online help with Rational Build Forge.

Enable Build Forge to control a build server using the installed Agent

You installed the Build Forge agent in Install and set up Rational Build Forge. The first step is to configure the Management Console to communicate with the agent process. This configuration will use functions from the Servers navigation panel in the Management console.

Create server authentication

The object holds the credentials the Management Console will use to log into the system running the Agent. The account used must have sufficient privileges to perform the tasks in the build process.

1. Click Server Auth under Servers.
2. Enter localhost auth for the Name, and the login parameters for the Administrator (or an account with sufficient privileges).
3. Click Save Server Authentication.
   
   

Create a Selector

Build Forge provides a powerful means of selecting a build server dynamically at build time. It is beyond the scope of this tutorial to describe this function, so you will hard wire the builds to a particular server. First you need to make a Selector that selects a server based on its name.

1. Click Selectors under Servers.
2. Enter build selector for the Name.
3. Click Save.
   
   

Enter Selector criteria

Build Forge allows multiple criteria to be used, such as free disk space, number of CPUs, and so on. This tutorial uses:

1. Default Name BF_NAME.
2. Operator == .
3. Enter build_server for the Value.
4. Yes for Required.
5. Click Save.
   
   

Create a server

The server object holds the connection information (host) and the link to the Server Authentication we created in Create server authentication. On the build server, the working directories for builds are set by the Path entry on this panel. Build Forge also lets you associate a server with an Environment variable specific to it.

1. Click Servers.
2. Enter build_server for the Name, c:\build for Path, and select localhost auth for Authentication. Leave the default values for the remaining fields.
3. Click Save.
   
   

Create a build directory

Build Forge will not be able to write to the directory specified in the path above unless it has been created. At a command prompt, enter md c:\build. 

Test the connection to the agent

To test the connection to the agent:

1. Select build_server.
2. Click Test Connection.
   
   

The Test Results tab will be displayed. After the Management Console has connected with and tested the agent, the display will be updated with the test results and the indicator on the icon for the server will show a green status.

Create and run a Hello World project

Now that the Management Console can control builds with an agent, you can write a Hello World project that will use the agent to echo a value. A Build Forge project contains several steps representing the commands that make up the build process.

1. To create the build project, it must be configured with a name and a selector. Consult the online help for a description of the remaining project configuration fields.
   • Click Projects.
   • Enter Hello World for the Name, and verify that Selector has defaulted to build selector.
   • Click Save Project.
     
     
2. Open the project by clicking on Hello World in the project list.
3. In the project, the steps are configured to perform the build process. In the Details tab, create a single step that echoes back a value:
   • Enter Echo Value for the Name
   • Enter echo Hello World in the Command area.
   • Leave the rest of the fields with default values for now.
   • b. Click Save Step.
     
     
4. Execute the project by clicking Start Project.
5. Leave the default values shown below, and click Execute.
6. The running build page will be displayed, showing progress through the project steps as they execute. The result from each step is also displayed.
7. Click the Step Name Echo value to see the log output from the step execution.
8. Scroll to the bottom of the log output. The expected Hello World message is shown.
   
   

Summary

You've accomplished a lot. The Build Forge Management console is running, and is connected to a "remote" server. You learned some basic Build Forge concepts, and are now familiar with the Build Forge deployment architecture and basic configuration. The architecture is able to control a simple build process on a remote server.

Get some rest and be ready for your second day, when you'll use everything created so far to begin building a real-world project: Jakarta Tomcat. Part 2 describes how Build Forge provides for the reuse of existing project scripting. It also covers how Build Forge can extend a simple compile and package build process by adding customization and deployment capability.

More@ http://www.ibm.com/developerworks/rational/tutorials/r-buildforge1/index.html