Before you can start buildign projects, it is recommended to take some time and set up the AnthillPro server's global settings. At the minimum, most users find the following necessary:
License activation.If not already done so, obtain a license and install it in the server. AnthillPro will not run without a license.
Set up security and users. If you are going to have more than the "admin" user, you will most likely need to configure security and add users.
Assign agent to an environment (configure agent). All builds and other similar processes run on an agent. In order for an agent to be available for a build, it needs to be assigned to an environment.
Set up the global repository. You build projects need to be associated with a specific SCM. You will need to set the global SCM integration prior to project configuration.
As part of installation, you should have already download and activated your license. If not, you will need to go to Supportal, the Urbancode support portal, where you downloaded the installation package and retrieve the license:
Go to Supportal to retrieve the license from your account.
Go to TEAMS/USERS > Licenses. If you do not see a license, either one does not exist for your account or you do not have permissions to download a license. Please contact your sales representative for more information.
Select the view license link on the right hand side of the appropriate license.
In the pop-up, click download.
Open the license, copy it, and paste it in the License field as outlined in either the Windows Installation or Linux/Unix Installation section.
In AnthillPro, you have detailed control over what a user can see and do. The system enables you to map your organizational structure by teams, activities, etc. For example, you can set up AnthillPro so that a developer only sees the projects they work on, or the QA team can only access the build artifacts.
Security management begins with Roles. In turn, each Role has corresponding Permissions to either restrict or allow a user to perform tasks, view pages, etc. Once the Roles and Permissions have been configured, Authorization Realms realms and then Authentication Realms are configured. Once security is configured, Audits may be performed for the who-when changes Administrative users make to the system.
| While you can configure a project as the admin user, and allow multiple people to concurrently log on to AnthillPro as the same user, it is advisable to add users -- and assign them a default role -- before going forward. This will allow you to see how AnthillPro integrates with other tools such as LDAP as well as allow you to control who gets notified for which events. |
To set up security and add users, see the Security section.
When an agent is installed and started on a host (i.e., a different machine), it contacts the AnthillPro central server. When a connection is established, the agent will show up under the Available tab (go to Agents > Agent > Available). The agents listed on the Available tab must be configured before they can start accepting work from the server and running commands, such as invoking your build script.
To configure an agent:
Go to Agents > Agent.
Select the Available tab. This page lists all the agents that can access the server, but are not available to run a build. If you installed an agent but it does not appear on this tab, make sure the agent is running and able to connect to the server (e.g., there is no firewall blocking server-agent communication).
Provide the following:
Name. Give the agent a descriptive name. The current name of the agent was given during the installation process. AnthillPro will automatically update the agent if it's name is changed.
Throughput Metric. The throughput metric provides a hint to AnthillPro’s load balancer. In a busy Build-Farm, it may be that several machines could handle a request, but each is already running builds. To determine which machine is best equipped to handle the additional build, the load balancer compares the machine’s throughput metric number to the number of jobs that are running on it. So a server with a metric of 10 will get a third job assigned to it before a server with a metric of 1 gets its second job.
Maximum Job Count. Agents can also be given a maximum number of jobs that they may run. If all agents a job can run on are at their maximum, it waits queued until a machine frees up.
Preferred Server. If utilizing distributed servers, select the appropriate server. In most cases, the agent should be connected to the preferred server via a LAN. Otherwise, select "none". See Distributed Servers and Agent Configuration.
Environments. You must check at least one environment. For running builds, most people select Build-Farm. This information will be used during project configuration.
If you are setting up AnthillPro for the first time, you can configure the agent to participate in all of the default environments (Build-Farm, Production, and QA). See Environment Management for a more detailed discussion.
Click Set then Done. The agent will automatically move to the Configured tab.
See also Agent Configuration for a more detailed discussion.
The Properties tab (see below) on the agent configuration page allows you to view or set custom variables on the agent.
The custom variables can indicate where build or testing tools are installed.
In the Locked Variables section, review the system and environment variables. Those are often used in agent filters.
See also Agent Configuration for a more detailed discussion.
Manage user access on the Security tab. Administrators can define what roles have access to read, write, or determine security for agents.
See also Agent Configuration for a more detailed discussion.
Once the agent has been installed, a proxy may be set up. Use an agent proxy for any agents where the direct agent-sever communication is prohibited. Once enabled, the proxy allows the agent to send logs, reports and other artifacts to the server. See Using Agent Proxies.
The SCM integrations enable AnthillPro to check out code, access the changelog, and label the repository (where supported). To do this, AnthillPro is first configured with your repository type at the System level, and then each workflow is associated with the source to be built.
The SCM integrations are implemented as job steps for a build job. Once you have completed source configuration, you can use the Job Wizard to automatically add steps to your build job -- this ensures that AnthillPro will consistently checkout and build the correct code.
Each SCM integration typically performs the following for any repository:
Checkout. This step enables you to define which version of code to check out from the SCM. For example, you can configure this step to checkout the latest source code; or perform a checkout based on a branch, label, date, etc. (depending on what your SCM supports).
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.
Label. AnthillPro can also apply a label to the source code used in the build (e.g., snapshot, baseline). This unique identifier for a build can be used to recreate a build if necessary.
SCM-specific commands. For most repository types, AnthillPro can also perform tasks only supported by that particular SCM.
To set up the global repository configuration, choose from the following (it is possible to configure multiple global repositories):
Enabled on the workflow, a trigger is an automated mechanism for kicking off a process, such as an automated build. If you use the repository-type trigger, AnthillPro will kick off a build every time a change is detected. In AnthillPro, you can use one of three trigger types:
Scheduled trigger. The simplest type to configure, the scheduled trigger fires either on a regular interval (e.g., every few minutes, hours, etc.) or can utilize a Cron expression for irregular, but recurring, schedules. When used for CI, the scheduled trigger polls the SCM for source changes. If changes are found, a build is kicked off. See Use Agent Filters and Quiet Periods for more detailed information.
Repository (commit) trigger. Many SCM types support commit triggers that allow AnthillPro to kick off a build at the time source changes are made. Repository triggers are far more efficient than scheduled triggers, as they don't poll the SCM, and are the most common trigger type used for CI builds. See Use Agent Filters and Quiet Periods for more detailed information.
If you are unsure if your SCM supports commit triggers, please check the SCM Tools section for instructions on configuring a commit trigger.
Event trigger. An advanced trigger type, the event trigger allows for a custom filter that taps into the AnthillPro event service and triggers actions when certain events occur. For example, an event trigger would listen for build completed events, check those events against the project’s dependencies, and force a build of the project if a dependency builds successfully.
| This section is for general trigger usage. If you followed the instructions for setting up a CI build, you should have already configured a trigger. If not, you can follow the process below. Otherwise, you can use this section as a basis for switching to a repository trigger. |
Go to Administration and select the workflow of the project you want to trigger.
On the Workflow page, select the Triggers tab and then click the New Trigger button.
Select Trigger type from the drop-down menu and click Select.
Configure trigger. Generally, you have the following options:
Name. Give a name that identifies this trigger.
Force. By default, AnthillPro does not force a build if the trigger does not find any code changes when the trigger fires. It is rare that you will want to force a build every time the trigger fires, so leave this filed blank.
Enabled. By default, when you create a new trigger it is enabled, which is what you want for a CI build.
Click Save then Done.
The next time the trigger fires, and it detects a source change, the build will take place. It will be identified (on the Dashboard) by the type of trigger that kicked of the build.
Note that if you are not seeing builds, it is most likely because no changes have been made to the source code.