Before you start
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.
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
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.
- 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.
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.
- Unzip the installation files.
- Run Setup. Select Install Rational License Server.
- Accept the default options for the rest of the license server installation. When setup is complete, click Finish.
- Start the License Key Administrator by selecting All Programs > IBM Rational > IBM Rational License Key Administrator.
- Select Import a Rational License File, and click Next.
- Browse to the location of the Evaluation License Key file.
- Open the file, and click Import.
- Verify that the licenses are valid, and click Import.
- Agree to restart the license server.
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.
- Unzip the installation file, then run it.
- When prompted, select the Complete setup.
- Select Install.
- Click Next until you see the window below. Select Configure the MySQL Server now, then click Finish.
- Click Next, select the Standard Configuration, and click Next.
- Select:
- Install As Windows Service
- MySQL for the Service Name
- Launch the MySQL Server Automatically
- Include Bin Directory in Windows PATH
and click Next.
- Enter a root password, click Next, then click Execute.
- Click Finish.
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.
- Open a command prompt and, as shown below, enter
mysql -uroot -p<password entered during mysql install>
- At the mysql prompt, enter
create database build;
- At the mysql prompt, enter
grant all on build.* to build identified by 'build';
- At the mysql prompt, enter
quit
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.
- Unzip the installation file, and run it.
- Click Next on the setup wizard Welcome panel.
- Select your destination folder.
- 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).
- Enter
MC1
for Location Name. Select Connect to existing database, and:- DB Name: build
- DB Type: MySQL
- DB Host: localhost
- Username: build
- Password: build
- 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.
- 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
- Enter
copy "c:\Program Files\MySQL\MySQL Server 5.0\bin\libmySQL.dll" "c:\Program Files\BuildForge\Apache\bin"
- Restart the Build Forge service by entering
net start bfengine
- Close the command prompt window.
- Double-click the Management Console icon on the desktop.
- Enter the User name
root
and Password root
, and click Login.
- You should then see the Management Console home page for the root user.
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.
- Unzip the installation file and run win-bfagent-7.0.1.211.exe.
- Accept all defaults throughout the agent installation panels.
- 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.
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.
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.
- Click Server Auth under Servers.
- Enter
localhost auth
for the Name, and the login parameters for the Administrator (or an account with sufficient privileges).
- Click Save Server Authentication.
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.
- Click Selectors under Servers.
- Enter
build selector
for the Name.
- Click Save.
Build Forge allows multiple criteria to be used, such as free disk space, number of CPUs, and so on. This tutorial uses:
- Default Name BF_NAME.
- Operator == .
- Enter
build_server
for the Value.
- Yes for Required.
- Click Save.
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.
- Click Servers.
- Enter
build_server
for the Name, c:\build
for Path, and select localhost auth for Authentication. Leave the default values for the remaining fields.
- Click Save.
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
.
To test the connection to the agent:
- Select build_server.
- 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.
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.
- 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.
- Open the project by clicking on Hello World in the project list.
- 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.
- Execute the project by clicking Start Project.
- Leave the default values shown below, and click Execute.
- The running build page will be displayed, showing progress through the project steps as they execute. The result from each step is also displayed.
- Click the Step Name Echo value to see the log output from the step execution.
- 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.