Creating a Project brings together two other AnthillPro concepts: Lifecycle Models and Environment Groups. When setting up a project for the first time, you can use the default options (given below) for simplicity. However, it is also possible to configure custom Models and Environment Groups: if you go this route, it may be worth reading the Concepts section first.
When getting started with AnthillPro, it is helpful to think of the build process (simply called the "build") as having three stages:
Input. Consists of the source code, located in an SCM. To run a build, AnthillPro will need to know where to find the source code.
Transformation. The actions necessary to generate the output. In AnthillPro, this corresponds to the workflow and job.
Output. The result of the transformation, called the build artifacts.
To achieve a successful build:
Make sure the AnthillPro server and at least one agent are installed and running.
Know the AnthillPro server URL (e.g., http://localhost:8080/), as well as your user name and password, to log on to AnthillPro.
The URL of the source repository (e.g., CVS, Subversion, TFS, etc.). Because AnthillPro will check out a copy the source code when a build is requested, you will also need to give AnthillPro access to the repository, usually assigning a user account to AnthillPro.
Configure a new project. This project, called a Life-Cycle Based project in AnthillPro, is composed of at least one workflow that will run the build.
Configure the repository (SCM). Let AnthillPro know about the source repository before you configure a workflow.
Create a new workflow. The workflow is AnthillPro's basic unit of process automation. It is where you define how the transformation (i.e., the build) will take place, as well where you will perform source configuration.
Create a new job. The job is the building block of the transformation, and is composed of a series of actions the server must perform (called "steps" in AnthillPro). The job, in turn, is added to the workflow.
Complete build process configuration. Before you can run a build, you need to tie the workflow and job into a complete build process.
Run a build. Once the configuration is done, you are ready to build!
To create a new project:
Go to the Administration page click the New Project icon.
On the Create a Project page, check the Life-Cycle Based project and click Select. In AnthillPro, it is the Life-Cycle Based project that is used to run a build.
For those just starting out, it is best to use the default settings and configurations, where possible, when setting up your build. Once you become more familiar with AnthillPro, you can begin to use the more advanced features.
Name. Give a name for this project. Typically, the name should reflect the type of project. You can map the name to your existing build infrastructure.
Description (optional). Give a description of this project. The descriptions allow you to convey more information about the project.
Life-Cycle Model. Select the Example Life-Cycle Model. This is the default model that ships with AnthillPro.
If you want to use your own Life-Cycle Model, see Using a Custom Lifecycle Model. Environment Group. Select the Default Environment Group that ships with AnthillPro.
Click Save.
A Life-Cycle Model allows you to create a reusable template that maps your organizational structure. For example, a typical set-up would be DEV, QA, PROD process (i.e., pipeline or life-cycle): a build starts out in development, is deployed to quality assurance for testing, and then finally sent to production for release. You would configure the Life-Cycle Model to apply a new status when a build is sent to QA, and one when the build is sent to PROD. Likewise, a stamp style (essentially a build identifier) can be applied to each build that corresponds to the status. This enables you to know exactly which build is in which environment because the status and stamp are recorded on the Dashboard.
Life-Cycle Models, then, give you control over how a build is identified, the different stages a build must go through on its way to the end user, how artifacts are handled, and which clean-up policies are enforced.
| Life-Cycle Models are closely associated with AnthillPro's Build Life concept: Much of what you configure in the Life-Cycle Model determines how a Build Life is identified and used. See Build Life for more. |
Once a Life-Cycle Model is created, it may be used for multiple projects with similar Life-Cycles without having to reconfigure a list of Statuses, Stamps, Artifact Sets, and Cleanup for the new project. This enables you to create system-wide standards that every team must use when configuring projects.
When getting started, it is usually best to use the default Lifecycle Model until you are familiar with how the models work. Once you have few builds going, and even deploying, you can create your own model that better reflects you organizational structure.
See Using Life-Cycle Models for a complete discussion.
Before you can configure a project's build workflow, you need to let AnthillPro know about the repository type you use (if not already done so as outlined in the Setting Up the Server section). The information you give in this section will eventually be shared by multiple projects.
Select your repository type from the list below and follow the instructions.
The workflow is AnthillPro's basic unit of process automation for a project. It is where you define how the transformation (build) will take place, as well as the source code that corresponds to the project (source configuration). During workflow creation, you will need to provide further information about the SCM type you configured on the System page.
Select the Add Workflow icon of your new project.
Next, check Originating workflow and click Select on the New Workflow page. In AnthillPro, it is the Originating workflow that is used to run build. Non-Originating workflows are secondary processes (such as deployments) that can be run on the build.
Workflow configuration:
Name. Give a name for this workflow. Typically, the name should reflect the type of work to be performed when this workflow runs. For example, "Trunk Build."
Description (optional). Give a description of this workflow. The description allows you to convey more information about the workflow.
Environment. Assign the workflow to the Build-Farm environment. In AnthillPro, the environment is the location where the build takes place. AnthillPro ships with 3 default environments:
Build-Farm. Generally, this is the environment that all builds take place within, and is most closely associated with Development. This is the environment you want your builds to run in.
QA. This environment is provided for performing quality assurance testing. Most often, when you are sending a build to testing, you want that workflow to run in this environment. See Setting Up a Deployment for more.
Production. This environment is typically used to deploy your builds once they are ready for production. See Setting Up a Deployment for more.
Notification Scheme. Select the Default Notification scheme. By default, AnthillPro will send an e-mail notification to all AnthillPro users on completion of the workflow. For now, don't worry if you aren't getting any e-mails. This will be covered in more detail when you set up a Continuous Integration build.
Priority. Use the default Normal Priority. Once you have a lot of projects going in AnthillPro, you may need to prioritize which workflows run first.
Skip Quiet Period. Select No, the default value. This will ensure that the build takes the most recent source code. It is not recommended to skip the workflow's quite period under most circumstances. By default, AnthillPro based the quiet period on the changelog, which is what you need when configuring scheduled builds. See Use Agent Filters and Quiet Periods for more.
Click Save.
Source Configuration. Select the repository you want to associated with this workflow and click Set. This should correspond to the repository you configured earlier.
Once the repository is selected, you will be able to configure additional properties that tie this workflow to the specific source that will be built. See the Source Configuration section of the repository type used by this workflow. When done, go to the next item.
Set stamp value. To complete workflow configuration you will need to add a value to the default stamp (DEV) under the Stamping Strategies menu. The stamp enables you to apply a custom identifier to a build, in addition to the Build Life which AnthillPro automatically generates.
Without a Stamp Style value, AnthillPro will not be able to complete a build.
Click the Create Value icon under the Action menu.
Stamp. Give the value AnthillPro will use to stamp the build. The simplest way to make the stamp unique for each build is to associate it with the Build Life number that AnthillPro automatically generates. For now, use the following to generate a stamp:
build_${bsh:BuildLifeLookup.getCurrent().getId()}The short BeanShell script looks up the current build ID and then applies that number to the stamp. So for Build Life 1 the stamp will be build_1; for Build Life 2 the stamp will be build_2, etc.
For a detailed discussion on Stamps, see the Stamping section. Click Save.
Click Done.
See Create a New Job.
Once a build has completed, the generated artifacts are still in the working directory. To have AnthillPro track the artifacts, and make them available for deployments, etc., the artifacts need to captured and delivered to Codestation, the artifact management system. Once the artifacts are in Codestation, AnthillPro will be able to keep track of them as well as any other process, such as deployment to testing, etc., the artifacts are subjected to.
Since AnthillPro does not know what artifacts you want captured, you will need to label them so they can be grouped and stored together. This is done by defining an artifact set on your build process. You can think of the artifact set as a grouping of build artifacts (files) that allows for fine-grained consumption of the artifacts. Once the artifacts are labeled and grouped into an artifact set, you will need to manually add a Deliver Artifact step to your build job.
To capture and deliver build artifacts:
Go to Administration and select the workflow you created in the Setting Up a Build section.
On the Workflow page, select the Artifacts tab, then click the New Artifact Config button.
Configure artifact set:
Artifact Set. Select an artifact set from the drop-down menu (using one of the defaults is fine). AnthillPro ships with 3 default artifacts sets that correspond to the most common tiers of a 3-tier web application:
APP. Used to group objects for deployment to the application tier of a 3-tier application.
DB. Used to group objects for deployment to the database tier of a 3-tier application.
WEB. Used to group objects for deployment to the web tier of a 3-tier application.
Generally, an artifact set is named for the type of objects which are grouped inside of them. The objects within an artifact set, in turn, are grouped by how the objects are going to be consumed. (For now, we are focusing on Artifact Sets used for deploying a project. In another section, we will cover using Artifacts Sets for dependency management.)
Base Directory. Here, you need to give the directory where the artifacts (say a jar or dll file) are placed once the build is complete. This directory is relative to the build's working directory. So if your build places the artifacts in a "dist" directory, you would specify
dist/here. Note that if you leave this filed blank, AnthillPro will include the entire contents of the working directory in the artifact set.Include Artifacts. List the artifacts to be retrieved from within the base directory. You can specify the names of files that reside in the base directory: e.g.,
myProjectArtifacts.zip. Or, if the artifacts are located in a sub directory, you specify something likebin/myProjectArtifacts.jar. Each include pattern must be entered on a separate line.You can also use the following wild cards to tell AnthillPro what to include in the artifact set:
**Indicates include every directory within the base directory.*Used to include every file. So, if you use*.zip, the files matching this pattern will be included.**/*Tells AnthillPro to retrieve the entire file tree underneath the base directory.
If you leave this filed blank, AnthillPro will include all the files in the base directory (if one was specified).
Advanced: To include symbolic links and empty directories, add the link/directory as part of your include pattern. See Configure Server Miscellaneous Settings. Exclude Artifacts. Give the patterns of the artifacts that should be skipped from the include. This field is set in the same way as the Include Artifacts field, only you are telling AnthillPro what NOT to include. If you leave this filed blank, AnthillPro will exclude no files.
Click Save.
To send the build artifacts to the management system (Codestation), you need to add the Artifact Delivery step to your build job. Go to the job configuration page of the job you created in the Setting Up a Build section.
Click the Insert After icon of the step prior to where this step should run. Remember, the steps run in order, so any step, such as the Artifact Deliver step, which deals with the build artifacts must come after the actual "build" step.
On the Steps page, expand the Artifacts folder, select Artifact Deliver, and click Select.
Configure step:
Name. Give a name for this step. A simple "Artifact Deliver" is sufficient.
Artifact Set. Select the artifact set you just finished configuring.
Show Additional Options. These are advanced settings. For a simple deployment, you can skip these settings.
Click Save.
If you configured more than one artifact set for the build, add an Artifact Deliver step for each set. For example, if you are collecting different artifacts into the APP, DB, and WEB artifact sets, then you will need three deliver steps -- one for each artifact set.
The next time your build runs, the artifacts will be delivered to the AnthillPro artifact management system. (If you like, you can force a manual build.) This will make the artifacts available on the Dashboard.
To view the artifacts, go to the Dashboard and select your build workflow. Click on the most recent Build Life (i.e., build number) and then select the Artifacts tab.
Once you have verified that the correct artifacts have been captured and delivered, see Create a Deployment Workflow. to send them to a different location.
The job is the building block of the transformation, and is composed of a series of distinct actions the server must perform (called "steps" in AnthillPro) to successfully run a build. For any job you create, the steps (actions) are executed by the server one at a time, in a specific order. When you are first starting out with AnthillPro, it is best practice to use the Job Wizard when creating a build job. That way you are ensured that the server will perform the correct action at the correct time.
To create a job, click the Add Job icon of your project. Note that a job can only be created after the project's originating workflow has been created. If you get a message saying, "You must create an originating workflow and configure a source config before creating any jobs," see Create a New Workflow before continuing.
Use the Job Wizard to create your build job. Check Yes and click Select. The Job Wizard will take you through the steps necessary to create a build job.
Set up the job. On the Job's main page, you configure a number of controls, mostly dealing with how AnthillPro should interact with source. When possible, beginners should use the default values. For any job, configure the following:
Name. Give a name for this job. Typically, the name should reflect the type of work to be performed by the job. For example, "Build."
Description (optional). Give a description of this job. The description allows you to convey more information about what this job does, etc.
Stamp Style. Choose the DEV stamping style configured during workflow creation.
For items such as Should Tag, Should Cleanup, Change Log Start Status, etc., use the default settings. These are advanced settings.
Click Next.
Add a builder. On the Builders tab, click Add a Builder.
For any job, you need to let AnthillPro know what builder you use when you build source code for this project. Choose your builder from the list below for instructions on configuring this item.
Click Next.
Click Done. It is not necessary to add a publisher to complete a build. Publishers are used to share information about the completed build or send the build artifacts to Codestation, AnthillPro's artifact management system.
Using the Job Wizard to create a build job is recommended, as it is the best way to ensure that your builds will be configured correctly. However, it is also possible to create a custom build job. What this job will look like, and what steps it contains, will depend on your processes and tools used. Generally, every build job should contain the following steps at a minimum:
Cleanup Step. Cleans up the workspace prior to populating it. This ensures that any files you might pick up from the build actually belong to the build and not a previous build.
Populate Workspace. Places the checked-out code (defined in the workflow's source configuration) in the workspace.
Get Changelog. The retrieved changelog is usually based on the changes made since the previous build. This step enables AnthillPro to extract data from the SCM and then store it in the AnthillPro data warehouse. Since AnthillPro stores the changelogs, it can parse the data, allowing you to override the default behavior. For example, you can select a starting point for the changelog based on criteria such as the latest production build.
Stamp. Applies a stamp to the build, which is used to identify the build within AnthillPro. See Stamping for more.
Get Dependency Artifacts. If your project depends on any other project, you need to specify it here. Otherwise, this step will just be skipped if no dependencies are defined.
Builder. Usually points to the location of tool or script used for the build.
Assign Status - Success. Applies the status when the build completes successfully.
Assign Status - Failure. Applies the status when the build fails.
This build configuration uses generic job steps -- which should suffice for most builds. However, most of the SCM integrations also include tool-specific steps (commands, etc.) that you can add to your build job. While these steps are not required for a basic build, they may be helpful as you design more complicated build jobs.
When configuring a job, the steps are available under the SCM folder. The tool-specific job steps that may be added to the generic build job or used to replace one of the generic steps where appropriate. For example, the ClearCase integration includes the following tool-specific steps that can be used to either replace or append the generic build:
ClearCase Changelog. Performs a ClearCase changelog. You can use this step in place of the standard step.
ClearCase Cleanup. Perform a cleanup of the current ClearCase working directory. You can use this step in place of the standard step.
ClearCase Label. ClearCase-specific label step. You can use this step in place of the standard step, if labels are being used.
Lock (ClearCase Base Dynamic Plugin only). Locks ClearCase resources. This steps adds ClearCase specific functionality to the build job.
Unlock (ClearCase Base Dynamic Plugin only). Unlocks ClearCase resources. This steps adds ClearCase specific functionality to the build job.
ClearCase Populate Workspace (Legacy integration only). Populates the workspace With source from ClearCase. You can use this step in place of the standard step.
Once the job has been created, it needs to be added to the originating workflow you created earlier. This process ties the build process together, and allows AnthillPro to generate the build artifacts when the build is run.
Go to the workflow you created in the Create a New Workflow section.
Select the Definition tab. The Workflow Definition is used to define the execution of the Job used by this workflow. A Workflow Definition has a single starting point and a single end point.
Use the default Embedded Definition. Click Select.
Click the Start button and select Insert Job After. Configure:
Job. Select the job you created in the Create a New Job section. The job will appear in the drop-down menu under "Project Jobs."
Pre-Condition. Select Always as the pre-condition for this job. That way, the job will always run.
Agent Filter. Select at least one agent from the Fixed Agent Selection list. Highlight the agent name in the list and click the plus sign (it will suffice to select one agent).
Once you are more familiar with AnthillPro, you can use agent filtering to determine which agent(s) a job can run on, including using scripted agent selection. For more on scripted agent selection scripts, see the scripting documentation in the Development Kit Bundle at tools > anthill3-dev-kit.zip. Working Directory. Select Source Config's Work Directory from the menu. This will ensure that the build takes place in the correct location.
Lock for Workflow. Use the default value of No. Locking is an advanced feature.
Click Insert Job.
Now that you have configured the build process, the next step is to run the build. See Run a Manual Build.
Running a manual build is a simple push-button process. Once on the workflow's Main tab, you will be presented with build options. For now, we simply need to get the project building.
Go to the Dashboard and select the workflow you want to build.
On the workflow's Main page, Click the Build button.
If you get a message saying "New Build Life Not Needed," make sure the Force option is selected and click the Build button again. Normally, AnthillPro only builds if the server finds source changes. Since this is the first build, you may have to force the build.
Delay Build (Advanced). To delay a build, check the box and then give the date and time you wish this workflow to run. This is a one-time event, not to be confused with a scheduled build. Once you configure a delayed build, it appears on the Current Activity tab under the Delayed Builds (or Planned Workflow Execution in some versions of AnthillPro) menu. There, you can delete the request for a delayed build.
Once the build has been started, you can check the build status on the workflow's My Activity tab. Refresh the page to update status.
When done, you can consider some Next Steps.
Continuous Integration. Now that you have the basic build going, try Setting Up Continuous Integration.
Notifications. You can configure AnthillPro to send out notifications about the state of your builds. See Basic Notifications.
Setting up a deployment process. Now that you have success with the basic CI build, you can turn your attention to the "output" phase of your build process: setting up an automated deployment process. See Setting Up a Deployment.
Add a dependency. Most project's will depend on another project. AnthillPro includes a dependency management system that allows you to use the build tool to define all your dependencies. See Defining a Basic Dependency.