<%@ page isELIgnored="true" %> <%@ taglib uri="cms" prefix="cms" %> Installation

Installation

To get AnthillPro running, you will need to install Java (on both the server and agent machines), the database, the server, and then the agent.

To evaluate AnthillPro, fill out the request an evaluation copy of AnthillPro form. Once your request is approved, you will be provided with login access to Urbancode's support team.

Most users have found the following procedures -- executed in the order presented -- helpful:

  1. Review the Install Recommendations section.

  2. Determine minimum system requirements. Before you get started, please review the System Requirements section. AnthillPro should run on most modern machines; however, if you are installing a production instance the System Requirements section outlines what current users have had success with.

  3. Select a database type. AnthillPro requires a backing database -- so if you are not using Derby (included in the download for evaluation purposes) you will need to decide which database to use. It is recommended to review the Database Installation section before continuing.

  4. Install Java on the server and agent machines. Both the server and agent require Java JRE 5 or greater be installed on the machine, as well as the JAVA_HOME environment variable set. The JAVA_HOME environment variable must point to the Java directory that you want AnthillPro to use.

    You may also use the appropriate version of the JDK. (It is recommended to use the Sun JDK. There have been some issues with the third-party JDK's from IBM and others.) See also 32- and 64-bit JVM Support.

  5. Install the database. AnthillPro ships with the Derby database, which should be fine for evaluation purposes but is not suitable for most enterprise applications. Currently, AnthillPro supports the following databases to store server and project information:

    Apache Derby (included in download)MySQL with InnoDB storage (4.1.22 and later)
    DB2 (requires 9.7 or later)Oracle, including RAC
    Microsoft SQL ServerPostgreSQL

    To install the database (except for Derby, which does not require a separate installation) you will need to:

    1. Download the appropriate JDBC driver file for your database. These are typically downloaded from the database vendor. If using the Derby database, you can skip this item.

    2. Create an empty database for AnthillPro to use with a dedicated user. If using the Derby database, you can skip this item. Follow the instructions given for your database type:

      Install Using DB2 (requires 9.7 or later)Install Using Oracle
      Install Using Microsoft SQL ServerInstall Using PostgreSQ

  6. Next, Download AnthillPro if not already done so.

  7. Finally, install the server and agent. See either Windows Installation or Linux/Unix Installation.

Install Recommendations

Since the AnthillPro agent performs most of the heavy lifting (e.g., performing builds, running tests, etc.), agent installation is critical to maximizing performance. Following are a few installation recommendations to reduce the chances of performance-related issues:

  • Install the server as a user account. Typically, the server should be installed as a dedicated system account when possible. However, AnthillPro will run very well as a Root (or Local System on Windows) and running that way is often the easiest way to start as you never get permissions errors.

  • Install the agent as dedicated system account. Ideally, the account used should be one created just for AnthillPro. Because AnthillPro agents are remote command execution engines, it is advisable to limit what they can do on each machine by creating a user just for the automation engine and grant it appropriate privileges. For example, if you plan on using the agent to run tests, it will need permissions to the testing tool executable, etc. If you install the agent as Root (or Local System on Windows), ensure that the processes you perform don't wipe out the file system, etc.

  • Do not install an agent on the AnthillPro server machine. Because the agent is resource intensive, installing one on the server machine will degrade server performance when a build, etc., is running on that agent. The agent is responsible for doing the "heavy lifting." When a build is run, the agent checks out the code, compiles it, performs any other processes you have configured, and then moves the build artifacts.

  • Install only one agent on a given machine where possible. As with installing an agent on the server box, having multiple agents on the same machine will have negative effects on each other ... resulting in slow builds, etc. This situation often arises when an organization installs multiple agents for different environments on the machine instead of installing one agent and assigning it to multiple environments. However, there may be instances where installing multiple agents is necessary. When this is the case, you will see varying performance when more than one agent is busy.

System Requirements

AnthillPro is OS agnostic, and will run on both Windows and UNIX-like systems. While the minimum requirements should suffice for initial evaluation purposes, it will be necessary to run the AnthillPro server on a server-class machine for most production deployments.

Server

Minimum requirements. The AnthillPro server will run on any modern business machine:

  • Processor. Single core, 1.5 GHz +.

  • Disk Space. 300 MB.

  • Memory. 2 GB, with 256 MB available to AnthillPro.

Recommended system requirements. For larger deployments (e.g., you will be running thousands of processes a day), most users have found the following guidelines helpful:

  • Small to medium sized server-class machines. It is recommended to have two machines: The primary machine and a cold standby for fail-over.

    The back-end database should be hosted on a separate machine, according to vendor guidelines. See also Database Requirements.

  • Processor. 2 CPU. 2+ core each.

  • RAM. 8 GB.

  • Storage. Your individual requirements depend on your usage, retention policies, and types of applications. In general, the more artifacts you keep in AnthillPro's artifact repository (Codestation), the greater the storage needs (e.g., you keep the generated artifacts from every CI build). Additionally, the server logs must also be taken into consideration -- over time log storage can add up.

    For further assistance in determining storage requirements, please contact support.

  • Network. Gigabit (1000) Ethernet with low latency to database.

Agent

Agents are designed to be minimally intrusive, and should only require 64-256 MB of memory and 100 MB on disk. Additional requirements are determined by the processes the agent will run.

For small evaluations, it is possible to install the agent on the same physical machine as the server; however, this should be avoided for large deployments of AnthillPro.

For further assistance in determining agent requirements (e.g., a heavily used build machine), please contact support.

32- and 64-bit JVM Support

The AnthillPro server must run against the 32-bit JDK for the Windows 2003 64-bit server. However, the 64-bit JDK can be used for agents that run builds. (It is recommended to use the Sun JDK. There have been some issues with the third-party JDK's from IBM and others.) Because AnthillPro does not require a multi-gigabyte heap, there is little advantage to using a 64-bit JVM for any operating system. However, for those on a 64-bit Windows platform, AnthillPro supports it with a 32-bit JVM; for other 64-bit platforms, AnthillPro uses a 64-bit JVM:

Operating SystemJVM 32JVM 64
Windows 32-bitYesN/A
Windows 64-bitYesNo
Non-windows 32-bitYesN/A
Non-windows 64-bitYesYes

Database Installation

If you are installing a production instance, you will most likely need to use a database other than Derby. Currently, AnthillPro supports the following databases to store information:

  • Oracle. Use the JDBC driver for Oracle 10.2 or higher, regardless of what version of the database is used.

    Starting with AnthillPro 3.7.3, you can use Oracle RAC (version 10g or later) as the backing database. For clean installs of AnthillPro, simply select Oracle as the backing database. If you are currently running AnthillPro with Oracle, switching to RAC is straightforward: after backing up your current database, update the base.xml and installed.properties files to use the new Oracle RAC configuration.

  • MySQL with InnoDB storage (works with 4.1.22 and later). It is recommended that the InnoDB storage engine be used. Also recommended is to use row or mixed binary logging format (not statement).

    • For MySQL 5, use the 5.0.8 driver version. The 5.1 version has known issues that will cause the AnthillPro server to throw an error. If you are using the 5.1 version, switch the driver jar file in the server's lib/ext directory and then restart.

    • For MySQL 5, use the 5.0.8 connector. There are some known issues in connector version 5.1.12 that result in errors.

  • Microsoft SQL Server. The MS SqlServer 2.0 driver (sqljdbc4.jar) will not work with AnthillPro. To install the server using Microsoft SQL Server, you will need to use one of the following drivers, depending on which version of Java the AnthillPro server uses:

    Java 5. Use either the 1.2 driver or the 2.0 sqljdbc.jar driver.

    Java 6. Use the 1.2 driver.

  • DB2 (requires 9.7 or later).

  • PostgreSQL. Due to a known defect with PostgreSQL 8.4.0, AnthillPro can't be installed with that version. Use version 8.3.7.

Install Using DB2

AnthillPro uses the Apache Derby database by default, but can also use DB2 9.7 or later as a database. An existing installation of DB2 9.7 or later must be installed either on the same machine as the AnthillPro server (for evaluation purposes only) or somewhere accessible on the network. You will need to provide the AnthillPro installation with the connection information to the DB2 9.7 or later database as well as a user login that is allowed to create tables.

Once the DB2 9.7 or later Server database and user have been created, obtain the correct JDBC driver that allows AnthillPro to connect to the DB2 9.7 or later database.

  1. Contact your DB2 9.7 or later vendor and request the JDBC driver that corresponds to the database version in use.

  2. After downloading AnthillPro, expand the archive.

  3. Copy the JDBC jar file into the anthill3-install/lib/ext directory.

  4. Proceed with the normal installation instructions until you reach the choice of database. See either Linux/Unix Installation or Windows Installation.

  5. When prompted for the database type, enter db2.

  6. Provide the following:

    • Driver. The JDBC driver class that AnthillPro will use to connect to the database. Default: com.ibm.db2.jcc.DB2Driver.

    • Connection string. Format of the connection string that is dictated by the JDBC driver you are using. For example, jdbc:db2://localhost:48665/anthill3.

  7. Follow the AnthillPro installation instructions for your operating system. See either Linux/Unix Installation or Windows Installation.

Install Using Oracle

AnthillPro uses the Apache Derby database by default, but can also use Oracle/Oracle RAC as a database. An existing installation of Oracle must be installed either on the same machine as the AnthillPro server (for evaluation purposes only) or somewhere accessible on the network. You will need to provide the AnthillPro installation with the connection information to the Oracle database as well as a user login that is allowed to create tables.

Starting with AnthillPro 3.7.3, you can use Oracle RAC (version 10g or later) as the backing database. For clean installs of AnthillPro, simply select Oracle as the backing database. If you are currently running AnthillPro with Oracle, switching to RAC is straightforward: after backing up your current database, update the base.xml and installed.properties files to use the new Oracle RAC configuration.

It is best to create a unique user for this database, and you may need to ensure that the user does not have Administrator privileges.

  • Use the JDBC driver for Oracle 10.2 or higher, regardless of what version of the database is used.

To install the AnthillPro server with Oracle, download either the zip or tar.gz distribution. Once you have the distribution downloaded, you may unpack it, but do not start the installation yet.

Before installation, obtain a JDBC driver for the AnthillPro server to use. (Use the JDBC driver for Oracle 10.2 or higher, regardless of what version of the database is used.) The JDBC driver is the Java code that allows the server to connect to the Oracle database. Oracle should provide a JDBC jar file with its installation. The driver is unique to the version of Oracle you are running. You need to locate the JDBC jar file and copy it into the expanded installation directory.

The JDBC jar file needs to be copied to the anthill3-install/lib/ext directory.

Proceed with the normal installation instructions until you reach the choice of database. You will be prompted for the type of database you want to use. Enter oracle. You will also need to provide information specific to the Oracle database.

First, give the JDBC driver class that AnthillPro will use to connect to the database. The default value is oracle.jdbc.driver.OracleDriver. It's a good idea to check your Oracle installation or driver file to see if the class is different before allowing the default value.

Second, you will be prompted for the JDBC connection string. The format of the connection string is dictated by the JDBC driver. See Oracle documentation.

Typically, it will match the following format:

jdbc:oracle:thin:@[DB_URL]:[DB_PORT]

Eg. jdbc:oracle:thin:@localhost:1521

  • If you are having trouble, and have a DBA account, try including the service name parameter, similar to:

    jdbc:oracle:thin:@[DB_URL]:[DB_PORT]:[SERVICE_NAME]

After providing the JDBC connection string, you will be prompted for the user and password. Enter those and complete the installation normally. If you receive errors during the installation, please copy the error output and contact support.

Install Using Microsoft SQL Server

AnthillPro can use Microsoft SQL server as its backing database. AnthillPro requires a newly created database in Microsoft SQL server, as well as a user that is allowed to create tables. It is best to install the database on a different machine as the server (except for evaluation purposes) under a unique user for AnthillPro to use.

You will also need to obtain the correct JDBC driver from Microsoft.

  • The MS SqlServer 2.0 driver (sqljdbc4.jar) will not work with AnthillPro. To install the server using Microsoft SQL Server, you will need to use one of the following drivers, depending on which version of Java the AnthillPro server uses:

    Java 5. Use either the 1.2 driver or the 2.0 sqljdbc.jar driver.

    Java 6. Use the 1.2 driver.

First, create a database and a user in your SQL Server database before installing AnthillPro. You can do this by running the following commands (change the password to something secure):

CREATE DATABASE anthill3;

USE anthill3;

CREATE LOGIN anthill3 WITH PASSWORD = 'password';

CREATE USER anthill3 FOR LOGIN anthill3 WITH DEFAULT_SCHEMA = anthill3;

CREATE SCHEMA anthill3 AUTHORIZATION anthill3;

GRANT ALL TO anthill3;

Once the Microsoft SQL Server database and user have been created, obtain a JDBC driver for the AnthillPro server to use. The JDBC driver is the Java code that allows the server to connect to the Microsoft SQL Server database. On their web site, Microsoft provides a JDBC driver jar to download. Please download the driver version that corresponds to your version of Microsoft SQL Server.

  • The MS SqlServer 2.0 driver (sqljdbc4.jar) will not work with AnthillPro. To install the server using Microsoft SQL Server, you will need to use one of the following drivers, depending on which version of Java the AnthillPro server uses:

    Java 5. Use either the 1.2 driver or the 2.0 sqljdbc.jar driver.

    Java 6. Use the 1.2 driver.

Locate the JDBC jar file and copy it into the AnthillPro installation directory at: anthill3-install/lib/ext.

Proceed with the normal installation instructions until you reach the choice of database. When prompted for the type of database to use, enter sqlserver to use the Microsoft SQL Server database. Also provide the JDBC driver class that AnthillPro will use to connect to the database. The default value is com.microsoft.sqlserver.jdbc.SQLServerDriver. Check your Microsoft SQL Server driver download to see if the class is different before using the default.

Next, give the JDBC connection string. The format of the connection string is dictated by the JDBC driver. See Microsoft SQL Server documentation.

Typically, it will match the following format:

jdbc:sqlserver://[DB_URL]:[DB_PORT];databaseName=[DB_NAME]

Eg. jdbc:sqlserver://localhost:1433;databaseName=anthill3

After providing the JDBC connection string, you will be prompted for the user and password. Enter those and complete the installation normally. If you receive errors during the installation, please copy the error output and contact support.

Install Using MySQL

AnthillPro uses the Apache Derby database by default, but you can also use MySQL (with InnoDB storage) as the database. An existing installation of MySQL (with InnoDB storage) must be installed either on the same machine as the AnthillPro server (if you are evaluating AnthillPro) or somewhere accessible on the network. You will need to provide the AnthillPro installation with the connection information to the MySQL database as well as a user login that is allowed to create tables. It is best to create a unique user for this database.

  • MySQL with InnoDB storage (works with 4.1.22 and later). It is recommended that the InnoDB storage engine be used. Also recommended is to use row or mixed binary logging format (not statement).

    • For MySQL 5, use the 5.0.8 driver version. The 5.1 version has some bugs that will cause the AnthillPro server to throw an error. If you are using the 5.1 version, switch the driver jar file in the server's lib/ext directory and then restart.

    • For MySQL 5, use the 5.0.8 connector. There are some known issues in connector version 5.1.12 that result in errors.

To install the AnthillPro server with MySQL, download either the zip or tar.gz distribution. Once you have the distribution downloaded, unpack it but do not start the installation yet.

First, create a database and a user in your MySQL database before installing AnthillPro. You can do this by running the following commands (change the password to something secure):

CREATE DATABASE anthill3;

GRANT ALL ON anthill3.* TO 'anthill3'@'%' 
IDENTIFIED BY 'password' WITH GRANT OPTION;

Before installation, obtain a JDBC driver for the AnthillPro server to use. The JDBC driver is the Java code that allows the server to connect to the MySQL database. MySQL should provide a JDBC jar file with its installation. The driver is unique to the version of MySQL you are running. Locate the JDBC jar file and copy it into the expanded installation directory. The JDBC jar file needs to be copied to the anthill3-install/lib/ext directory.

Proceed with the normal AnthillPro installation instructions until you reach the choice of database. You will be prompted for the type of database you want to use, so enter mysql. You will also need to provide need to provide the JDBC driver class that AnthillPro will use to connect to the database. The default value is com.mysql.jdbc.Driver. Check your MySQL installation or driver file to see if the class is different before accepting the default value.

Next, you will be prompted for the JDBC connection string. The format of the connection string is dictated by the JDBC driver. See MySQL documentation.

Typically, it will match the following format:

jdbc:mysql://[DB_URL]:[DB_PORT]/[DB_NAME]

Eg. jdbc:mysql://localhost:3306/anthill3

After providing the JDBC connection string, you will be prompted for the user and password. Enter those and complete the installation normally. If you receive errors during the installation, please copy the error output and contact support.

Install Using PostgreSQL

  • Due to a known defect with PostgreSQL 8.4.0, AnthillPro can't be installed with that version. Use version 8.3.7.

AnthillPro uses the Apache Derby database by default, but can also use PostgreSQL as a database. An existing installation of PostgreSQL must be installed either on the same machine as the AnthillPro server (for evaluation purposes only) or somewhere accessible on the network. You will need to provide the AnthillPro installation with the connection information to the PostgreSQL database as well as a user login that is allowed to create tables.

Once the PostgreSQL Server database and user have been created, obtain the correct JDBC driver that allows AnthillPro to connect to the PostgreSQL database.

  1. Go to www.PostgreSQL.org and download the JDBC driver for the version of PostgreSQL you use.

  2. After downloading AnthillPro, expand the archive.

  3. Copy the JDBC jar file into the anthill3-install/lib/ext directory.

  4. Proceed with the normal installation instructions until you reach the choice of database. See either Linux/Unix Installation or Windows Installation.

  5. When prompted for the database type, enter postgres.

  6. Provide the following:

    • Driver. The JDBC driver class that AnthillPro will use to connect to the database. Default: org.postgresql.Driver.

    • Connection string. Format of the connection string that is dictated by the JDBC driver you are using. For example, jdbc:postgresql://localhost:5432/anthill3.

  7. Follow the AnthillPro installation instructions for your operating system. See either Linux/Unix Installation or Windows Installation.

If you receive errors during the installation, please copy the error output and contact support.

Download AnthillPro

The installation package is available from the Urbancode Support Portal. If you are evaluating AnthillPro, the Supportal account where you download AnthillPro also gives you access to the support team -- where you can create a support ticket.

  1. Go to the Urbancode Support Portal. You must already be a license holder to access Supportal. If you do not have an account, please create one.

  2. Go to the PRODUCTS tab and select the version of AnthillPro you are downloading.

  3. Select the appropriate command-line installer. The contents of both packages are the same:

    • anthill3-<version>.tar.gz. Command line installer for Unix/Linux.

    • anthill3-<version>.zip. Command line installer for Windows.

    AnthillPro allows you to install Agents on any supported platform, regardless of the operating system the server is installed on. To do so, simply run the appropriate script included in the install package you chose. See either Installing the Agent (Windows) or Installing the Agent (Linux/Unix).

  4. See either Windows Installation or Linux/Unix Installation.

Windows Installation

To complete an installation, yinstall the server and at lest one agent. Typically, an agent is installed on a different machine as the server to avoid performance issues. When the server and agent are on the same machine, a busy build environment can slow down the server.

For evaluation purposes, installing the agent and server on the same machine should suffice. If you do this, it is best to install the agent in its own directory (e.g., c:\anthill-agent) and not in the server's directory.

Before you continue, ensure that you have the correct JVM/JDK for the server and agent. (It is recommended to use the Sun JDK. There have been some issues with the third-party JDK's from IBM and others.) If you are using a database other than Derby, make sure you have reviewed the Installation section and have gathered the appropriate driver, etc.

Server Installation (Windows)

For newer versions of Windows, you will need to execute an Administrator Command Prompt to install as a Windows Service. This can be done by right clicking cmd.exe and selecting "Run As Administrator."
To install the AnthillPro server:

  1. Download the anthill3-<version>.zip file.

  2. Expand the zip file using a tool like WinZip. Expanding will create an anthill3-install directory.

  3. Open the anthill3-install directory created in the previous step in Windows.

  4. If you are using a database other than Apache Derby, copy the JDBC driver file(s) into the anthill3-install\lib\ext directory. See Database Requirements.

  5. Run the install script install-server.bat.

  6. Provide the following information:

    • Directory where the AnthillPro server should be installed. For example: C:\Program Files\anthill3\server. If the directory does not already exist, enter Y to have the installer create the directory. Default is Y.

    • Home directory of the JRE/JDK used to run the server. For example: C:\Program Files\Java\jre1.6.0_07.

    • Port used to communicate with the agent(s). Recommended default value is 7915.

    • Port on which AnthillPro server should listen for remoting or distributed servers. Default is 4567.

    • IP address that the server web UI should listen on. We suggest leaving this blank so that AnthillPro listens on all available IP addresses.

    • Secured connections using SSL. If using a secured connection for all web UI communication, enter Y.

      When using SSL, you need to turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

      If using a caching proxy, see Caching and SSL before continuing. Under certain conditions, using HTTPS may effect server performance.

      • If using a secured connection for HTTP requests, give the port the AnthillPro sever should listen on. Recommended default is 8443.

      • Unsecured HTTP port for the Web UI. This will be used to redirect unsecured requests to the secured HTTPS port when using HTTPS for the Web UI. Default is 8080.

    • HTTP port for the Web UI (if not using SSL). Default is 8080.

    • Database type (if other than the embedded Derby database). See Database Requirements.

    • Database user name. Default is anthill3.

    • Database password. Default is password.

  7. Install as Windows service (optional). Type Y to install as Windows service. Type N to finish installation process. Note that when installing as a service, AnthillPro only captures the value for the PATH variable. The values captured at installation will always be used, even if you later make changes.

    For newer versions of Windows, you will need to execute an Administrator Command Prompt to install as a Windows Service. This can be done by right clicking cmd.exe and selecting "Run As Administrator."

  8. To automatically install the AnthillPro server as a Windows service, enter:

    • Service name and click OK. Default is ah3server. (A unique name is required for each instance.)

    • Login for the installed server and click OK. Default is .\localsystem.

    • Yes to automatically start ah3server service.

    To manually install the AnthillPro server as a Windows service (optional):

    For newer versions of Windows, you will need to execute an Administrator Command Prompt to install as a Windows Service. This can be done by right clicking cmd.exe and selecting "Run As Administrator."

    • Run ah3server.cmd install uniqueservicename (located in the server's bin\service directory).

    • Provide the service name and account information.

To run the AnthillPro server and complete installation:

  1. In Windows, go to the AnthillPro server directory created during installation. For example, C:\Program Files\anthill3\server. Enter the bin directory.

  2. Run: start_ah3server.cmd.

  3. Alternatively, from the command line run the start command bin\ah3server.cmd.

  4. When the AnthillPro server has started, open a web browser and give the AnthillPro URL. For example, http://localhost:8080.

  5. Complete installation:

    • External URL. Enter the URL users will use to access AnthillPro. This URL will be used to generate links back to the application in e-mail notifications, as well as for some agent communication. The URL may include http(s):// and any non-standard ports. For example http://localhost:8080 if you are using default installation values.

    • Administrator E-mail Address. Give the e-mail address that should be notified about system issues. The Administrator account will have complete access to AnthillPro, and is the initial user that must set up security. See Security.

    • Administrator Password. Enter the password the AnthillPro administrator (created above) will use to access AnthillPro.

      Note that this password (and the user name admin) will be required to complete installation of the Distributed Web interface if the AnthillPro server is going to be used in conjunction with the Distributed Web product. For information on the Distributes Web interface, contact .

    • Confirm Administrator Password. Enter the password again.

    • License. Paste your AnthillPro license in the text field after retrieving it from Supportal.

      1. Go to Supportal to retrieve the license from your account.

      2. 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.

      3. Select the view license link on the right hand side of the appropriate license.

      4. In the pop-up, click download.

      5. Open the license, copy it, and paste it in the License field.

      If you are evaluating AnthillPro, you download a 30-day, temporary license. The only difference between this and a production license is the expiration date. If you need a new production license, please contact your sales representative or create a Supportal ticket with your request.

  6. Click Complete.

    The application can now be accessed in the web browser. If you log out, give the user name admin and the password set in Item Five to log back in.

  7. Select pre-installed Plugins to activate/deactivate. AnthillPro ships with pre-configured integrations that are written as Plugins. If you choose to deactivate any of the Plugins, you will not be able to use the AnthillPro integration with that tool until you reactivate it. If you don't know what tool integrations you want deactivated, you can leave them all active to start with and then edit the setting later. Click Done to go to the Dashboard.

Installing the Agent (Windows)

When installing the agent in a production environment, most people typically create a dedicated user that is responsible for running the agent (i.e., they create an "Anthill" user on the machine the agent is being installed on).

  • Note that for evaluation purposes, you can simply run the agent as the "Admin" user.

In general, the agent will need the appropriate rights in order to communicate with the AnthillPro server; to communicate with any tools AnthillPro will integrate with (e.g., repository, testing tool, issue tracking tool, e-mail/IM, etc.); and to perform other tasks you will want AnthillPro to perform. Each agent should have permission to:

  • Create a cache. By default the cache is located in the home directory of the user running AnthillPro. However, the cache may be moved or disabled.

  • Open a TCP connection. The agent must use a TCP connection to communicate with the AnthillPro server's JMS port.

  • Open a HTTP(S) connection. The agent must be able to connect to the AnthillPro UI to download artifacts from the AnthillPro artifact repository (Codestation).

  • Access the file system. Many agents will need read/write permissions to items on the file system that are expected to go through AnthillPro.

To install the AnthillPro agent:

  1. Download the anthill3-<version>.zip file.

  2. Expand the zip file using a tool like WinZip. Expanding will create an anthill3-install directory.

  3. Open the anthill3-install directory created in the previous step in Windows.

  4. Run the install script install-agent.bat. For advanced agent installation, see also Unattended Agent Installation Scripts.

  5. Provide the following information:

    • Directory where the AnthillPro agent should be installed. For example: C:\Program Files\anthill3\agent. To have the installer create the directory, enter Y.

    • Home directory of the JRE/JDK used to run the agent. Default is C:\Program Files\Java\jre1.6.0_07.

    • Relay connection. Enter the default N if not using Urbancode's Distributed Servers product, available under separate license. If using Distributed Servers, see Installing Distributed Servers before continuing.

      If you are interested in using the Agent Relay for agent-server communication, contact .

    • Enter the host name or address of the AnthillPro server. Default is localhost.

    • Enter the port which the AnthillPro server will use for internal communication. Default is 7915.

    • Determine if internal communication should use SSL. Default is N.

      When using SSL, you need to turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

      • If using SSL, determine if communication should be mutually authenticated. Default is N.

  6. Enter name of agent.

  7. Type Y to automatically install the AnthillPro agent as a Windows service. Type N to complete installation process.

    For newer versions of Windows, you will need to execute an Administrator Command Prompt to install as a Windows Service. This can be done by right clicking cmd.exe and selecting "Run As Administrator."

  8. Install Agent as Windows Service. Note that when installing as a service, AnthillPro only captures the value for the PATH variable. The values captured at installation will always be used, even if you later make changes.

    For newer versions of Windows, you will need to execute an Administrator Command Prompt to install as a Windows Service. This can be done by right clicking cmd.exe and selecting "Run As Administrator."

    If automatically installing the AnthillPro agent as a Windows service, enter:

    • Service unique name. Default is ah3agent. (A unique name is required for each instance.)

    • Login for installed agent service. Default is .\localsystem.

    • Yes to automatically start service.

    To manually install the AnthillPro agent as a Windows service:

    • Run ah3agent.cmd install uniqueservicename (located in bin\service folder of the AnthillPro directory).

    • Provide the service name and account information.

To run the AnthillPro agent:

  1. In Windows, navigate to the AnthillPro agent directory created during the installation. Default is: C:\Program Files\anthill3\agent. Enter the bin directory.

  2. Run the start script: start_ah3agent.cmd.

  3. Alternatively, from the command line run the start command bin\ah3agent.cmd start.

  4. See Configure Agents. You will not be able to build a project until an agent is properly configured.

Linux/Unix Installation

To complete an installation, install the server and at lest one agent. Typically, an agent is installed on a different machine as the server because the agent is responsible for performing resource-intensive tasks such as builds. When the server and agent are on the same machine, a busy build environment can effect server performance.

For evaluation purposes, installing the agent and server on the same machine should suffice. If you do this, it is best to install the agent in its own directory.

Server Installation (Linux/Unix)

To install the AnthillPro server:

  1. Download the anthill3-<version>.tar.gz file.

  2. Open a UNIX shell to the directory containing the above downloaded file.

  3. Extract the downloaded file. Type: tar -zxf anthill3-<version>.tar.gz.

    • On some installations of Solaris and HP-UX the default tar command will not properly handle our tar files. You may need to use \ install GNU tar.

      When installing AnthillPro on Solaris, it is recommended to use korn shell (ksh).

  4. cd anthill3-install.

  5. If you are using a database other than Apache Derby, copy the JDBC driver file(s) into the anthill3-install/lib/ext directory. See Database Requirements.

  6. Run the install script ./install-server.sh.

    You can also install the server to run automatically using the init.d script. To do so, go to the install directory: /anthill3-install/bin/server/init, copy the ah3server file into your init directory, and make sure the INSTALL MODIFICATION section contains the correct information. Once your modifications are completed, make the file available to run.

  7. Provide the following:

    • Directory where the AnthillPro server should be installed. For example: /opt/anthill3/server. If the directory does not already exist, enter Y to have the installer create the directory. Default is Y.

    • Home directory of the JRE/JDK used to run the server.

    • Port on which AnthillPro server should listen for remoting or distributed servers. Default is 4567.

    • IP address that the server web UI should listen on. We suggest using the default 'all IP addresses bound to machine' so that AnthillPro listens on all available IP addresses.

    • JMS port of the server. This is the port used for internal communications between the agent(s) and server. Recommended default value is 7915.

    • Secured connections using SSL. If using a secured connection for all web UI communication, enter Y. If using a caching proxy, see Caching and SSL before continuing. Under certain conditions, using HTTPS may effect server performance.

      When using SSL, you need to turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

      • If using a secured connection for HTTP requests, give the port the AnthillPro sever should listen on. Recommended default is 8443.

      • Unsecured HTTP port for the Web UI. This will be used to redirect unsecured requests to the secured HTTPS port when using HTTPS for the Web UI. Default is 8080.

    • HTTP port for the Web UI (if not using SSL). Default is 8080.

    • Database type (if other than the embedded Derby database). See Database Requirements.

    • Database user name. Default is anthill3.

    • Database password. Default is password.

To run the AnthillPro server and complete installation:

  1. Open a UNIX shell to the directory where you installed the server. If you took our suggestion, then this is: /opt/anthill3/server.

  2. cd bin.

  3. Run the start script: ./ah3server start.

  4. The application can now be accessed in the web browser.

  5. Complete installation:

    • External URL. Enter the URL users will use to access AnthillPro. This URL will be used to generate links back to the application in e-mail notifications, as well as for some agent communication. The URL may include http(s):// and any non-standard ports. For example http://localhost:8080 if you are using default installation values.

    • Administrator E-mail Address. Give the e-mail address that should be notified about system issues. The Administrator account will have complete access to AnthillPro, and is the initial user that must set up security. See Security.

    • Administrator Password. Enter the password the AnthillPro administrator (created above) will use to access AnthillPro.

      Note that this password (and the user name admin) will be required to complete installation of the Distributed Web interface if the AnthillPro server is going to be used in conjunction with the Distributed Web product. For information on the Distributes Web interface, contact .

    • Confirm Administrator Password. Enter the password again.

    • License. Paste your AnthillPro license in the text field after retrieving it from Supportal.

      1. Go to Supportal to retrieve the license from your account.

      2. 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.

      3. Select the view license link on the right hand side of the appropriate license.

      4. In the pop-up, click download.

      5. Open the license, copy it, and paste it in the License field.

      If you are evaluating AnthillPro, you download a 30-day, temporary license. The only difference between this and a production license is the expiration date. If you need a new production license, please contact your sales representative or create a Supportal ticket with your request.

  6. Click Complete.

    The application can now be accessed in the web browser. If you log out, give the user name admin and the password set in Item Five to log back in.

  7. Select pre-installed Plugins to activate/deactivate. AnthillPro ships with pre-configured integrations that are written as Plugins. If you choose to deactivate any of the Plugins, you will not be able to use the AnthillPro integration with that tool until you reactivate it. If you don't know what tool integrations you want deactivated, you can leave them all active to start with and then edit the setting later. Click Done to go to the Dashboard.

Installing the Agent (Linux/Unix)

When installing the agent in a production environment, most people typically create a dedicated user that is responsible for running the agent (i.e., they create an "Anthill" user on the machine the agent is being installed on).

  • Note that for evaluation purposes, you can simply run the agent as the "Admin" user.

In general, the agent will need the appropriate rights in order to communicate with the AnthillPro server; to communicate with any tools AnthillPro will integrate with (e.g., repository, testing tool, issue tracking tool, e-mail/IM, etc.); and to perform other tasks you will want AnthillPro to perform. Each agent should have permission to:

  • Create a cache. By default the cache is located in the home directory of the user running AnthillPro. However, the cache may be moved or disabled.

  • Open a TCP connection. The agent must use a TCP connection to communicate with the AnthillPro server's JMS port.

  • Open a HTTP(S) connection. The agent must be able to connect to the AnthillPro UI to download artifacts from the AnthillPro artifact repository (Codestation).

  • Access the file system. Many agents will need read/write permissions to items on the file system that are expected to go through AnthillPro.

See Agent Installation (VMS) if you want to install the agent for VMS. The process is manual, and uses an existing, but modified, UNIX-installation.

To install the Agent:

  1. Download the anthill3-<version>.tar.gz file.

  2. Open a UNIX shell to the directory containing the above downloaded file.

  3. Extract the downloaded file. Type: tar -zxf anthill3-<version>.tar.gz.

    • On some installations of Solaris and HP-UX the default tar command will not properly handle our tar files. You may need to use \ install GNU tar.

      When installing AnthillPro on Solaris, it is recommended to use korn shell (ksh).

  4. cd anthill3-install.

  5. Run the install script ./install-agent.sh.

    You can also install the agent to run automatically using the init.d script. To do so, go to the install directory: /anthill3-install/bin/agent/init, copy the ah3agent file into your init directory, and make sure the INSTALL MODIFICATION section contains the correct information. Once your modifications are completed, make the file available to run.

  6. Provide the following information:

    • Directory where the AnthillPro agent should be installed. For example: /opt/anthill3/agent. To have the installer create the directory, enter Y.

    • Home directory of the JRE/JDK used to run the agent.

    • Relay connection. Enter the default N if not using Urbancode's Distributed Servers product, available under separate license. If using Distributed Servers, see Installing Distributed Servers before continuing.

      If you are interested in using the Agent Relay for agent-server communication, contact .

    • Enter the host name or address of the AnthillPro server. Default is localhost.

    • Enter the port which the AnthillPro server will use for internal communication. Default is 7915.

    • Determine if internal communication should use SSL. Default is N.

      • If using SSL, determine if communication should be mutually authenticated. Default is N.

  7. Enter name of agent.

To run the AnthillPro agent, follow the steps below:

  1. Open a UNIX shell to the directory where you installed the agent. If you took our suggestion, then this is: /opt/anthill3/agent.

  2. cd bin.

  3. Run the script: ./ah3agent start.

  4. See Configure Agents. You will not be able to build a project until an agent is properly configured.

Configure SSL

AnthillPro allows the server and agents to communicate securely using SSL in two modes: unauthenticated and mutual authentication. In unauthenticated mode, the communication between the server and agents is secured with SSL, but there is no authentication to verify the server or agent credentials.

When using SSL, turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

In mutual authentication mode, the communication between server and agent is secured with SSL and authentication takes place to verify the server is really the server and the agent is really the agent.

Configuring Server-Agent SSL

To use SSL between the server and agent, both the sides need a private key created in a keystore. This key and keystore is created during the installation process of the server and agent. There should be a ah3.keystore file in the conf directory of each installation. If there is not, please contact support for assistance.

To turn SSL on, make sure the server is running and go to the Web UI. On the System tab, click the Server Settings link under the Server menu. In the new window, enable the Use SSL Between Server and Agents setting. After this, restart the server. That completes the server configuration for enabling SSL.

When using SSL, turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

For each agent installed, first shutdown the agent, and then go to the conf/agent directory and edit the agent's installed.properties file (note: this file was previously agent.properties on older installations). The settings in the file that controls the SSL communication is locked/server.secure. If this property is not present add the line: locked/server.secure=Y.

Start the agent, and go in to the server Web UI to verify that the agent shows up as online. To further test that communication is working properly, go to the Agent and select the Properties tab to validate the agent properties are retrieved correctly.

Configuring Mutual Authentication

For mutual authentication between server and agent communication, you must facilitate a public key exchange between the two. To do this, export the public key from the certificate keystore and import it into the keystore of that which you are communicating with: Export the server key and import it into the agent keystore, and export the agent key and import it into the server keystore. Also ensure that every agent using mutual authentication has the locked/server.mutual_auth=Y property in the installed.properties (or agent.properties) file.

  1. To export the public key from the server certificate keystore, open a command-line shell to the server installation’s conf directory and run:

    keytool -export -keystore ah3.keystore -storepass changeit 
    -alias ah3_server -file ah3_server.crt

  2. This file needs to be copied to your agents. Place it into the agent installation’s conf directory and run the following to import it:

    keytool -import -keystore ah3.keystore -storepass changeit 
    -alias ah3_server -file ah3_server.crt -keypass changeit -noprompt

  3. While on the agents, run the following from their installation’s conf directory to export their public keys (change the name of the file argument to match the agent name):

    keytool -export -keystore ah3.keystore -storepass changeit 
    -alias ah3_agent -file [agent_name].crt

  4. Open the Agent's installed.properties (or agent.properties) file (in the conf\agent directory) in a text editor. Set the locked/server.mutual_auth property to true: locked/server.mutual_auth=Y and save your changes.

  5. Copy the agent public keys to the server’s conf directory and run the following command to import them (change the name of the file argument to match your file name and the name of the alias argument to match your agent name):

    keytool -import -keystore ah3.keystore -storepass changeit 
    -alias [agent_name] -file [agent_name].crt -keypass changeit -noprompt

  6. To complete mutual authentication, make sure the server is running, go to the System page, and click the Server Settings link under the Server menu.

  7. In the next window, enable the Enforce Mutual Authentication setting.

  8. Restart agent(s).

  9. Verify that communication is working properly between server and agents.

To list the certificates that are loaded into a keystore, run the following from the same directory:

keytool -list -keystore ah3.keystore -storepass changeit

SSL and Distributed Servers

It is possible to configure the AnthillPro server to use SSL with the Distributed Web Interface. To do so, import an existing certificate and switch to https. Before you begin, make sure AnthillPro is not running any jobs (you can do this on the Current Activity page). The ports listed in the examples may be different than those used by your AnthillPro system. See Using SSL with Distributed Web Interface.

Agent Installation (VMS)

AnthillPro Agent installation must be done manually for VMS, as there are no installation scripts included with the product. This is easiest if an existing Unix-based installation is modified and packaged for installation on the VMS system.

The only prerequisite for the target VMS system:

  • JVM installed must be at least Java 1.4.

  • The logical JAVA$FORK_PIPE_STYLE must be set to 1.

There are no modifications to the VMS environment as a result of the agent installation.

To installl:

  1. Choose any existing Unix-based agent installation and make a complete copy.

    • Run: cp –R agent vmsAgent

  2. Modify classpath.conf file.

    • Run: vi vmsAgent/bin/classpath.conf

    • Change all paths in file to match the target VMS path. VMS paths must be specified using Unix-style as opposed to VMS-style. For example:

      dir /opt/anthill3/agent/conf/client

      becomes

      dir /VSI_KIT_ROOT1/ANTHILL/KIT/AGENT/CONF/CLIENT

  3. Modify agent.properties file.

    • Run: vi vmsAgent/conf/agent/agent.properties

    • Change all paths in file to match the target VMS path. VMS paths must be specified using Unix-style as opposed to VMS-style. For example:

      anthill3/temp.dir=/opt/anthill3/agent/var/temp

      becomes

      anthill3/temp.dir=/VSI_KIT_ROOT1/ANTHILL/KIT/AGENT/VAR/TEMP

    • The following is a list of all path properties that need to be changed.

      anthill3/temp.dir

      anthill3/var.dir

      locked/agent.home

      locked/java.home

      anthill3/work.dir

      anthill3/logs.dir

      anthill3/root.dir

      locked/ant.home

    • Change the agent name property (replace {VMS host name} with the actual host name).

      locked/anthill3.name <http://anthill3.name>={VMS host name}

    • Change the agent ID property.The ID can be anything as long as it's unique from every other agent (host name may be used if desired).

      locked/anthill3.id <http://anthill3.id>={desired ID}

  4. Create a VMS DCL file to enable launching of the agent process.

    • Run: vi vmsAgent/bin/AH3AGENT.COM <http://AH3AGENT.COM>

    • Add the following content to the file.

      $ ! setup.com <http://setup.com> 
$ 
$ @sys$startup:java$150_setup.com <http://150_setup.com> 
$ 
$ java -jar [.]launcher.jar [.]classpath.conf 
  "com.urbancode.anthill3.main.agent.AnthillAgent" 
$

  5. Package the VMS agent installation.

    Run:

    cd vmsAgent zip –r anthill_vms_agent.zip *

    • Run: cd vmsAgent zip –r anthill_vms_agent.zip *

  6. Copy the agent package to the target VMS host.

  7. Unzip the agent package in desired location (must match paths used in steps 2 and 3).

  8. Start the agent.

    • Run:

      SET DEFAULT VSI_KIT_ROOT1:[ANTHILL.KIT.AGENT.BIN]

      @AH3AGENT

  9. Open a browser and go to http://anthill.unix.swx.ch <http://anthill.unix.swx.ch/>

    • Log in as "admin" using password from Server Installation.

    • Click the System tab. In some versions of AnthillPro, agents have their own top-level Agents tab.

    • Click Agents in the Environment Administration section.

    • Find the new agent under Available Agents.

    • Click Configure.

    • Select the Build-Farm checkbox.

    • Click Set then Done.

Unattended Agent Installation Scripts

To install a large number of agents quickly, AnthillPro provides an Unattended Agent Installation script that invokes the agent installer. The script allows you to specify how many agents to install in a chosen directory, and set the requisite agent properties. The script uses all of the agent installation defaults, so you will most likely need to modify the script to fit your needs. Once the script is modified, it is also possible to customize it; e.g., install agents in different directories, install agents with different names, etc.

The Unattended Agent Installation script is available with the standard AnthillPro installation package. There are two versions of the script, one for installing agents on Windows and one for installing agents on Linux/Unix.

Unattended Agent Installation Script (Windows)

Below is a copy of unattended-install-agent.bat, which is included in the AnthillPro Installation Package. The script invokes the AnthillPro agent installer, and requires you to set all the agent properties that are given during a command-line installation. To get started:

  1. Download the appropriate AnthillPro Installation Package.

  2. Open unattended-install-agent.bat file in a text editor.

  3. Set the agent properties. Please refer to Installing the Agent (Windows) and the AnthillPro server install.properties file (located in the \conf\server\ directory) for the appropriate settings.

  4. Once the properties are set, remove lines 11 and 12, which prevent the script from accidentally running. The easiest way to do this is simply comment out the lines as follows:

    REM echo REMOVE THIS LINE AFTER MODIFYING THIS SCRIPT FOR YOUR NEEDS
REM GOTO END

    • Note that if the unattended-install-agent.bat script is not in the same directory as the install-agent.bat file, you will have to make additional modifications to script to install the agent(s).

  5. Save your changes.

  6. Open the command line, point it to the anthill3-install directory, and run unattended-install-agent.bat.

  7. Start the agent(s). See Installing the Agent (Windows).

Example Unattended Agent Installation Script (Windows):

@echo off
setlocal
REM ###########################################################################
REM WARNING:  This script is an example of how to create an unattended
REM installation script.  The parameters below as well as the script content
REM may and probably WILL need to be modified to accommodate your situation.
REM
REM The parameters which can be modified to alter the unattended installation.
REM ###########################################################################

echo REMOVE THIS LINE AFTER MODIFYING THIS SCRIPT FOR YOUR NEEDS
GOTO END

set AGENT_JAVA_HOME=C:\Program Files\Java\jre6

set CONNECT_VIA_RELAY=N
set INSTALL_AGENT_REMOTE_HOST=<PUT ANTHILL3 SERVER HOSTNAME HERE>
REM IF CONNECT_VIA_RELAY
REM set INSTALL_AGENT_REMOTE_PORT=7916
REM ELSE
set INSTALL_AGENT_REMOTE_PORT=7915

set INSTALL_AGENT_REMOTE_PORT_SSL=N
set INSTALL_AGENT_REMOTE_PORT_MUTUAL_AUTH=N
REM IF CONNECT_VIA_RELAY
set INSTALL_AGENT_RELAY_HTTP_PORT=20080
REM ELSE
REM set INSTALL_AGENT_RELAY_HTTP_PORT=

set INSTALL_AGENT_NAME=anthill3-agent
set INSTALL_AGENT_DIR=C:\Program Files\anthill3\batch\agent

set INSTALL_SERVICE=N
set INSTALL_SERVICE_NAME=ah3agent
set INSTALL_SERVICE_LOGIN=.\localsystem
set INSTALL_SERVICE_PASSWORD=nopass
set INSTALL_SERVICE_AUTOSTART=N

set agent_count=10

REM ###########################################################################
REM The installation script
REM ###########################################################################

cd %~dp0

set ANT_HOME=opt\apache-ant-1.7.1
set CLASSPATH=

set i=0
:LOOP
 CALL opt\apache-ant-1.7.1\bin\ant.bat -f install.with.groovy.xml ^
  "-Dinstall-agent=true" ^
  "-Dinstall-server=false" ^
  "-Dinstall.java.home=%AGENT_JAVA_HOME%" ^
  "-Dinstall.agent.connect_via_relay=%CONNECT_VIA_RELAY%" ^
  "-Dinstall.agent.jms.remote.host=%INSTALL_AGENT_REMOTE_HOST%" ^
  "-Dinstall.agent.jms.remote.port=%INSTALL_AGENT_REMOTE_PORT%" ^
  "-Dinstall.agent.relay.http.port=%INSTALL_AGENT_RELAY_HTTP_PORT%" ^
  "-Dinstall.agent.remote.port.ssl=%INSTALL_AGENT_REMOTE_PORT_SSL%" ^
  "-Dinstall.agent.remote.port.mutual_auth=%INSTALL_AGENT_REMOTE_PORT_MUTUAL_AUTH%" ^
  "-Dinstall.agent.name=%INSTALL_AGENT_NAME%-%i%" ^
  "-Dinstall.agent.dir=%INSTALL_AGENT_DIR%-%i%" ^
  "-Dinstall.service=%INSTALL_SERVICE%" ^
  "-Dinstall.service.name=%INSTALL_SERVICE_NAME%" ^
  "-Dinstall.service.login=%INSTALL_SERVICE_LOGIN%" ^
  "-Dinstall.service.password=%INSTALL_SERVICE_PASSWORD%" ^
  "-Dinstall.service.autostart=%INSTALL_SERVICE_AUTOSTART%" ^
	install-non-interactive
  set /a i=i+1
  if "%i%"=="%agent_count%" goto END
  goto LOOP
:END

Unattended Agent Installation Script (Linux/Unix)

Below is a copy of unattended-install-agent.sh, which is included in the AnthillPro Installation Package. The script invokes the AnthillPro agent installer, and requires you to set all the agent properties that are given during a command-line installation. To get started:

  1. Download the appropriate AnthillPro Installation Package.

  2. Open unattended-install-agent.sh file in a text editor.

  3. Set the agent properties. Please refer to Installing the Agent (Linux/Unix) and the AnthillPro server install.properties file (located in the /conf/server/ directory) for the appropriate settings.

  4. Once the properties are set, remove lines 9 and 10, which prevent the script from accidentally running. The easiest way to do this is simply comment out the lines as follows:

    # echo REMOVE THIS LINE AFTER MODIFYING THIS FILE FOR YOUR PURPOSES
# exit

    • Note that if the unattended-install-agent.sh script is not in the same directory as the install-agent.sh file, you will have to make additional modifications to script to install the agent(s).

  5. Save your changes.

  6. Open the command line, point it to the anthill3-install directory, and run unattended-install-agent.sh.

  7. Start the agent(s). See Installing the Agent (Linux/Unix) .

Example Unattended Agent Installation Script (Linux/Unix):

#!/bin/sh
################################################################################
# WARNING:  This script is an example of how to create an unattended
# installation script.  The parameters below as well as the script content
# may and probably WILL need to be modified to accommodate your situation.
#
# The parameters which can be modified to alter the unattended installation.
################################################################################
echo REMOVE THIS LINE AFTER MODIFYING THIS FILE FOR YOUR PURPOSES
exit

AGENT_JAVA_HOME=/usr/lib/jvm/java-6-sun-1.6.0.10

CONNECT_VIA_RELAY=N
INSTALL_AGENT_REMOTE_HOST=<YOUR SERVER HOSTNAME HERE>
# IF CONNECT_VIA_RELAY
#INSTALL_AGENT_REMOTE_PORT=7916
# ELSE
INSTALL_AGENT_REMOTE_PORT=7915

INSTALL_AGENT_REMOTE_PORT_SSL=N
INSTALL_AGENT_REMOTE_PORT_MUTUAL_AUTH=N
# IF CONNECT_VIA_RELAY
INSTALL_AGENT_RELAY_HTTP_PORT=20080
# ELSE
# INSTALL_AGENT_RELAY_HTTP_PORT=

INSTALL_AGENT_NAME=anthill3-agent
INSTALL_AGENT_DIR=/opt/anthill3/batch/agent

INSTALL_SERVICE=N
INSTALL_SERVICE_NAME=ah3agent
INSTALL_SERVICE_LOGIN=.\localsystem
INSTALL_SERVICE_PASSWORD=nopass
INSTALL_SERVICE_AUTOSTART=N

agent_count=10

################################################################################
# The installation script.
################################################################################
PREVIOUS_DIR=$(pwd)
PREVIOUS_ANT_HOME=$ANT_HOME
PREVIOUS_CLASSPATH=$CLASSPATH
OUR_ANT_VERSION=1.7.1

SHELL_NAME=$0
SHELL_PATH=$(dirname ${SHELL_NAME})

if [ "." = "$SHELL_PATH" ] 
then
    SHELL_PATH=$(pwd)
fi
cd ${SHELL_PATH}

export ANT_HOME=opt/apache-ant-${OUR_ANT_VERSION}

chmod +x opt/apache-ant-${OUR_ANT_VERSION}/bin/ant

export CLASSPATH=

# Run the installation.
i=0
while [ $i -lt "$agent_count" ]
do
  opt/apache-ant-${OUR_ANT_VERSION}/bin/ant \
    "-Dinstall-agent=true" \
    "-Dinstall-server=false" \
    "-Dinstall.java.home=$JAVA_HOME" \
    "-Dinstall.agent.connect_via_relay=$CONNECT_VIA_RELAY" \
    "-Dinstall.agent.jms.remote.host=$INSTALL_AGENT_REMOTE_HOST" \
    "-Dinstall.agent.jms.remote.port=$INSTALL_AGENT_REMOTE_PORT" \
    "-Dinstall.agent.relay.http.port=$INSTALL_AGENT_RELAY_HTTP_PORT" \
    "-Dinstall.agent.remote.port.ssl=$INSTALL_AGENT_REMOTE_PORT_SSL" \
    "-Dinstall.agent.remote.port.mutual_auth=$INSTALL_AGENT_REMOTE_PORT_MUTUAL_AUTH" \
    "-Dinstall.agent.name=$INSTALL_AGENT_NAME-$i" \
    "-Dinstall.agent.dir=$INSTALL_AGENT_DIR-$i" \
    "-Dinstall.service=$INSTALL_SERVICE" \
    "-Dinstall.service.name=$INSTALL_SERVICE_NAME" \
    "-Dinstall.service.login=$INSTALL_SERVICE_LOGIN" \
    "-Dinstall.service.password=$INSTALL_SERVICE_PASSWORD" \
    "-Dinstall.service.autostart=$INSTALL_SERVICE_AUTOSTART" \
    -f install.with.groovy.xml install-non-interactive
  i=$(($i+1))
done

# Restore previous state
cd ${PREVIOUS_DIR}
export ANT_HOME=${PREVIOUS_ANT_HOME}
export CLASSPATH=${PREVIOUS_CLASSPATH}

Run with Apache Server

The embedded Tomcat instance can be configured to run behind Apache HTTPD. This is desirable to make the AnthillPro UI available on the standard HTTP/HTTPS ports (80/443) without the security risk of running the JVM as root.

  • $ANTHILL3_HOME should be replaced with your AnthillPro server home directory. Host names (anthill3.example.com) should be replaced by values appropriate to your site.

See also Optimizing Server Performance.

Tomcat Configuration

Locate the Tomcat server configuration file, server.xml, which is in $ANTHILL3_HOME/opt/tomcat/conf. Add a connector child element to the service element (this should be near the top of the file):

<Connector port="8009" minProcessors="5" maxProcessors="256" 
protocol="AJP/1.3" />

AnthillPro must be restarted for this to take effect.

Apache 2.0 Configuration

Configuring Apache to use mod_jk is somewhat complicated. First, for Apache 2.0, use mod_jk version 1.2.19. You may need to look in the Tomcat project archives to find the appropriate binary. Later versions only support Apache 2.2. After downloading, extract mod_jk.so and add it to the Apache modules directory.

Add the following to Apache’s httpd.conf:

LoadModule jk_module modules/mod_jk.so

JkWorkersFile "conf/workers.properties"

<VirtualHost *:80>
  ServerName anthill3.example.com
  JkMount /* anthill3
</VirtualHost>

Create a file called workers.properties in the Apache conf directory:

worker.list=anthill3
worker.anthill3.type=ajp13
worker.anthill3.host=anthill3.example.com
worker.anthill3.port=8009

The worker.anthill3.host should match the value of ServerName in httpd.conf and worker.anthill3.port must match the value of the Connector port in server.xml.

Apache 2.2 Configuration

For Apache 2.2, use mod_jk version 1.2.21 or later. The binaries are accessible via the normal Tomcat/Jk connector download page. The configuration is identical to Apache 2.0.

In addition to mod_jk, Apache 2.2 adds a new proxy module, mod_proxy_ajp designed to work with Tomcat. This module is part of Apache 2.2, so a separate download is not necessary.

The Tomcat configuration is the same as above.

Add these lines to httpd.conf:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

<VirtualHost *:80>
  ServerName anthill3.example.com
  ProxyPass / ajp://internal.example.com:8009/
  ProxyPassReverse / ajp://internal.example.com:8009/
</VirtualHost>

Changing the Context Path on Apache-based Installations

The above directions assume the Anthill UI is running as the root context (that is, the UI would be viewable at http://anthill3.example.com/), but it is possible to run the UI with a different context path (e.g., http://www.example.com/anthill3). This is not a fully supported configuration and upgrading may become difficult.

To change the context path from / to /anthill on Apache-based installations, do the following: Edit server.xml and change the context element to have path="/anthill" and docBase="anthill". Then, rename $ANTHILL3_HOME/opt/tomcat/webapps/ROOT to $ANTHILL3_HOME/opt/tomcat/webapps/anthill.

In httpd.conf, update the URLs in the JkMount and ProxyPass... directives:

JkMount /anthill/* anthill3

or:

ProxyPass /anthill ajp://internal.example.com:8009/anthill 
ProxyPassReverse /anthill ajp://internal.example.com:8009/anthill

Additionally, add JkMount and ProxyPass... lines for the AnthillPro Help:

JkMount /anthillpro-help/* anthill3

or:

ProxyPass /anthillpro-help ajp://internal.example.com:8009/anthillpro-help

ProxyPass /anthillpro-help ajp://internal.example.com:8009/anthillpro-help 
ProxyPassReverse /anthillpro-help ajp://internal.example.com:8009/anthillpro-help

Changing the Context Path on Non-Apache Installations

To change the context path if AnthillPro is not behind an Apache server:

  1. Shut down AnthillPro.

  2. Rename the opt/tomcat/webapps/ROOT directory to the context you want to use.

  3. Edit opt/tomcat/conf/server.xml and change the context path and docbase attribute, for example 

    Context path="/anthill" docBase="anthill"

  4. Delete the opt/tomcat/work/Catalina directory.

  5. Start AnthillPro.

Installing Distributed Servers

Installation of Distributed Servers is similar to installing the central AnthillPro server. You will need a Distributed Web Interface license (in addition to the AnthillPro Server license) and, if connecting agents via the Agent Relay, an Agent Relay license.

To complete installation of Distributed servers, do the following:

  1. Install the AnthillPro main server. See Installing AnthillPro.

  2. Retrieve Distributed Servers license and load it in the AnthillPro server UI. See Upload Distributed Servers License.

  3. Install the Distributed Web Interface. See either Install Distributed Web Interface (Windows) or Install Distributed Web Interface (Linux/Unix).

  4. Install the Agent Relay (optional). See either Install Agent Relay (Windows) or Install Agent Relay (Linux/Unix).

  5. Install Agents. See either Install the Agent with Relay (Windows) or Install the Agent with Relay (Linux/Unix).

  6. Configure Agents to use the Distributed Web Interface for Codestation caching (optional). See Distributed Servers and Agent Configuration.

See also Distributed Servers: Best Practices for Installation.

Prerequisites: Distributed Web Interface Installation

  • JRE v1.5.0 (or greater) installed in the OS. Set the JAVA_HOME environment variable to point to the Java directory.

  • The AnthillPro server must already be installed. See Installing AnthillPro.

  • You must have a license for the Distributed Web Interface and/or Agent Relay, depending on how you plan to install Distributed Servers. Contact support for more information. See Upload Distributed Servers License.

  • The 'admin' account and password, created during AnthillPro server installation, must be available to complete the installation.

  • Familiarity with the Distributed Servers system architecture.

Upload Distributed Servers License

Once the AnthillPro server is installed and running (see Installing AnthillPro), retrieve the Distributed Servers license and upload it in the AnthillPro server UI.

  1. Go to the AnthillPro download page and log in to your account.

  2. Get a copy of your Distributed Servers license.

  3. Log in to the AnthillPro server as the 'admin'.

  4. Go to System > License under the Server menu.

  5. Paste the license in the Upload New License text field.

  6. Click Upload then Done.

  7. See Install Distributed Web Interface (Windows) or Install Distributed Web Interface (Linux/Unix).

Install Distributed Web Interface (Windows)

Make sure the AnthillPro server is already installed. See Windows Server Installation from zip File.

  1. Download the anthill3-distributed-web-<version>.zip file from the Urbancode Support Portal.

  2. Expand the zip file using a tool like WinZip. Expanding will create a anthill3-distributed-web directory.

  3. Open the anthill3-distributed-web directory in Windows.

  4. Run: install.cmd.

  5. Provide the following:

    • Directory where the Distributed Web Interface is to be installed. Enter the directory where the Distributed Web interface should be installed. Default is C:\Program Files\anthill3\dist-web. If the directory does not already exist, enter Y to have the installer create it.

    • Java home. Enter the Java home used to run the Distributed Web interface. The installer will attempt to find it, or use the JAVA_HOME variable. If not found, enter it here.

    • AnthillPro server IP or host name. Enter the IP or host name of the AnthillPro server. This is the host, or IP, on which the Distributed Web Interface can contact the main AnthillPro server. To determine the AnthillPro server IP or host name, go to: AnthillPro UI > System > Server Settings.

    • HTTP or HTTPS for AnthillPro server. If the AnthillPro server is using HTTPS, enter Y. Otherwise, enter N. Default is N. To find if the AnthillPro server uses HTTPS, go to the AnthillPro server's \conf\server\ directory and open the install.properties file in a text editor. Check the install.server.web.always.secure= property.

    • AnthillPro server port for web connection. Enter the port on which the AnthillPro server listens for web connections.

      • If using HTTP, the default port used for web connections is 8080.

      • If using HTTPS, the default port used for web connections is 8443.

      To find the port, go to the AnthillPro server's \conf\server\ directory and open the install.properties file in a text editor. Check the install.server.web.port= property.

    • Legacy communication port. Enter the legacy port on which the AnthillPro server listens for remote connections. If AnthillPro is being installed for the first time, use the default 4567.

      For 3.6.x communication has been changed, so the legacy port must be updated. To find the port, go to the AnthillPro server's \conf\server\ directory and open the install.properties file in a text editor. Check the install.server.port= property.

    • New AnthillPro internal communication port. Enter the new communication port which the AnthillPro server listens on. The new default value is 7915.

    • Distributed Web Interface communication port. Enter the port on which the Distributed Web interface should use for communication. Default is 7917.

    • Secure communication. Determine if using secure communication. To use secure connection between the agent, the Relay (if used), and the AnthillPro server, enter Y. Default is N.

      • Mutual authentication. If using secure communication, determine if mutual authentication is required. To require mutual authentication, enter Y. Default is N.

    • Distributed Web Interface user name. Enter the user name to use when connecting the Distributed Web interface to the AnthillPro server. Default is admin. This is the admin account created during installation of the AnthillPro server. The default user name, admin, should be used, along with the current password associated with this account.

    • Password. Enter the password to use when connecting the Distributed Web interface to the AnthillPro server. Default is admin. This is the password associated with the admin account created during installation of the AnthillPro server. The default user name, admin, should be used, along with the current password associated with this account.

    • Name. Give a name for this Distributed Web node. Each node should have a unique, meaningful name. Default is dist-web.

    • Distributed Web IP or host name. Enter the IP or hostname the Distributed Web will listen on. Default is 0.0.0.0. The default value will allow the Distributed Web to listen on all IPs associated with the AnthillPro server.

    • HTTP or HTTPS for Distributed Web Interface. Determine if the Distributed Web should use HTTPS or not. Enter Y to use HTTPS, or N to use HTTP. Default is N.

      • Distributed Web port for web connections. If using HTTPS, enter the port on which the Distributed Web will listen for web connections. Default is 8443.

    • Distributed Web port for web connections. Enter the port on which the Distributed Web interface will listen for web connections. Default is 8080.

  6. Start the Distributed Web Interface.

    • To start the Distributed Web in a new shell, go to the Distributed Web's \bin directory and run start_ah3web.cmd.

    Or:

    • To start the Distributed Web from the command line, run ah3web run.

  7. If using the Agent Relay, see Install Agent Relay (Windows). Otherwise, follow the instructions given in Installing the Agent (Windows).

Install Agent Relay (Windows)

If Agent communication is routed through the relay proxy, the Relay must be installed before installing the agents that will use it.

Before installing the Agent Relay, make sure the AnthillPro server is installed (see Windows Server Installation from zip File) and that the license has been uploaded to the AnthillPro server (see Upload Distributed Servers License).

  1. Download the anthill3-agent-relay-<version>.zip file.

  2. Expand the zip file using a tool like WinZip. Expanding will create a anthill3-agent-relay directory.

  3. Open the anthill3-agent-relay directory.

  4. Run the install script install.cmd.

  5. Provide the following:

    • Location of Agent Relay. Give the directory where the Agent Relay should be installed. Default is C:\Program Files\anthill3\relay. If the directory does not already exist, enter Y to have the installer create it. Default is Y.

    • Java home. Enter the Java home used to run the Distributed Web interface. The installer will attempt to find it, or use the JAVA_HOME variable. If not found, you will need to enter it here.

    • Name. Give a name for the relay. Each Agent Relay should be given a unique, meaningful name. Default name is agent-relay.

    • Agent Relay IP or host name. Enter the IP or hostname the Agent Relay will listen on. Default is 0.0.0.0. The default value will allow the Agent Relay to listen on all IPs associated with the AnthillPro server.

    • Port Relay listens on for HTTP requests. Enter the port on which the Agent Relay should listen for HTTP requests coming from the agent(s). Default is 20080.

    • Port Relay uses for communication. Enter the port on which the Agent Relay will use for communication with the agent. Default is 7916.

    • AnthillPro server IP or host name. Enter the IP or host name of the AnthillPro server. This is the host, or IP, on which the Agent Relay can contact the main AnthillPro server. To determine the AnthillPro server IP or host name, go to: AnthillPro UI > System > Server Settings.

    • AnthillPro server communication port. Enter the port which the AnthillPro server uses for communication. If you used the default value during server installation, use 7915. If the AnthillPro server uses a different port, go to the AnthillPro server's \conf\server\ directory and open the install.properties file in a text editor. The port is listed in the install.server.jms.port= property.

    • Secure communication. Determine if using secure communication between the server, the relay, and the agents. To use secure connection, enter Y. Default is N.

      • Mutual authentication. If using secure communication, determine if mutual authentication is required. To require mutual authentication, enter Y. Default is N.

  6. Optionally, install Agent Relay as Windows Service:

    For newer versions of Windows, you will need to run as Administrator from the command line to install as a Windows Service. For example: C:\Windows\system32>.

    • Open the command line and point it to the Agent Relay's \bin\service directory.

    • Run: ah3relay.cmd install.

    • Follow the instructions on the installer to run the service with Log on Service rights.

    • Enter the user account name, including the domain path, to run the service. Default is .\localsystem.

    • Enter Y to start service automatically. Default is N. Service must be manually started the first time.

    • To remove the Agent Relay as Windows Service, run: ah3relay.cmd remove.

  7. Start the Agent Relay.

    • To start the Agent Relay in a new shell, go to the Agent Relay's \bin directory and run start_ah3relay.cmd.

    Or:

    • To start the Agent Relay from the command line, run ah3relay run.

  8. See Install the Agent with Relay (Windows).

Install the Agent with Relay (Windows)

Make sure the AnthillPro server, Distributed Web Interface (if used), and Agent Relay are installed. See Windows Server Installation from zip File; Install Distributed Web Interface (Windows); and Install Agent Relay (Windows).

If you are not using the Agent Relay, follow the agent installation instructions found in Installing AnthillPro.

  1. Download the anthill3-<version>.zip file. If you only installing agents, you can download the anthill3-agent-<version>.zip file, which is much smaller.

  2. Expand the zip file using a tool like WinZip. Expanding will create a anthill3-install directory.

  3. Open the anthill3-install directory.

  4. Run the install script install-agent.bat.

  5. Provide the following information:

    • Directory where the AnthillPro agent should be installed. For example: C:\Program Files\anthill3\agent. To have the installer create the directory, enter Y.

    • Java home. Enter the Java home used to run the Agent. The installer will attempt to find it, or use the JAVA_HOME variable. If not found, you will need to enter it here.

    • Relay connection. Enter Y. Before continuing, make sure the Agent Relay is already installed (separate download). See Install Agent Relay (Windows).

    • Host name or address of the Agent Relay. Default is localhost.

    • Port which the Agent Relay will use for communication. Default is 7916.

    • Determine if communication should be secured using SSL. Default is N.

      When using SSL, you need to turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

      • If using SSL, determine if mutual authentication should be used. Default is N.

    • HTTP port the Agent Relay will use for web requests. Default is 20080.

  6. Name. Give a unique, meaningful name for every agent installed.

  7. Type Y to automatically install the AnthillPro agent as a Windows service. Type N to complete installation process.

    For newer versions of Windows, you will need to run as Administrator from the command line to install as a Windows Service. For example: C:\Windows\system32>.

  8. If automatically installing the AnthillPro agent as a Windows service, enter:

    • Service unique name. Default is ah3agent. (A unique name is required for each instance.)

    • Login for installed agent service. Default is .\localsystem.

    • Yes to automatically start service.

To manually install the AnthillPro agent as a Windows service:

For newer versions of Windows, you will need to run as Administrator from the command line to install as a Windows Service. For example: C:\Windows\system32>.

  • Run ah3agent.cmd install uniqueservicename (located in bin\service folder of the AnthillPro directory).

  • Provide the service name and account information.

To run the AnthillPro agent:

  1. In Windows navigate to the AnthillPro server directory created during the installation. If you took our suggestion, then this is: C:\Program Files\anthill3\agent. Enter the bin directory.

  2. Run the start script: start_ah3agent.cmd.

  3. Alternatively, from the command line run the start command bin\ah3agent.cmd start.

  4. See Distributed Servers and Agent Configuration.

Install Distributed Web Interface (Linux/Unix)

Make sure the AnthillPro server is already installed. See Linux/Unix Server Installation from tar.gz File.

  1. Download the anthill3-distributed-web-<version>.tar.gz file.

  2. Expand the archive. Expanding will create the anthill3-distributed-web directory.

  3. Open the anthill3-distributed-web directory.

  4. Run: install.sh.

  5. Provide the following:

    • Directory where the Distributed Web Interface is to be installed. Enter the directory where the Distributed Web interface should be installed. Default is /opt/anthill3/dist-web. If the directory does not already exist, enter Y to have the installer create it.

    • Java home. Enter the Java home used to run the Distributed Web interface. The installer will attempt to find it, or use the JAVA_HOME variable. If not found, you will need to enter it here.

    • AnthillPro server IP or host name. Enter the IP or host name of the AnthillPro server. This is the host, or IP, on which the Distributed Web Interface can contact the main AnthillPro server. To determine the AnthillPro server IP or host name, go to: AnthillPro UI > System > Server Settings.

    • HTTP or HTTPS for AnthillPro server. If the AnthillPro server is using HTTPS, enter Y. Otherwise, enter N. Default is N. To find if the AnthillPro server uses HTTPS, go to the AnthillPro server's /conf/server/ directory and open the install.properties file in a text editor. Check the install.server.web.always.secure= property.

    • AnthillPro server port for web connection. Enter the port on which the AnthillPro server listens for web connections.

      • If using HTTP, the default port used for web connections is 8080.

      • If using HTTPS, the default port used for web connections is 8443.

      To find the port, go to the AnthillPro server's /conf/server/ directory and open the install.properties file in a text editor. Check the install.server.web.port= property.

    • Legacy communication port. Enter the legacy port on which the AnthillPro server listens for remote connections. If AnthillPro is being installed for the first time, use the default 4567.

      For 3.6.x communication has been changed, so the legacy port must be updated. To find the port, go to the AnthillPro server's /conf/server/ directory and open the install.properties file in a text editor. Check the install.server.port= property.

    • New AnthillPro internal communication port. Enter the new communication port which the AnthillPro server listens on. The new default value is 7915.

    • Distributed Web Interface communication port. Enter the port on which the Distributed Web interface should use for communication. Default is 7917.

    • Secure communication. Determine if using secure communication. To use secure connection between the agent, the Relay (if used), and the AnthillPro server, enter Y. Default is N.

      • Mutual authentication. If using secure communication, determine if mutual authentication is required. To require mutual authentication, enter Y. Default is N.

    • Distributed Web Interface user name. Enter the user name to use when connecting the Distributed Web interface to the AnthillPro server. Default is admin. This is the admin account created during installation of the AnthillPro server. The default user name, admin, should be used, along with the current password associated with this account.

    • Password. Enter the password to use when connecting the Distributed Web interface to the AnthillPro server. Default is admin. This is the password associated with the admin account created during installation of the AnthillPro server. The default user name, admin, should be used, along with the current password associated with this account.

    • Name. Give a name for this Distributed Web node. Each node should have a unique, meaningful name. Default is dist-web.

    • Distributed Web IP or host name. Enter the IP or hostname the Distributed Web will listen on. Default is 0.0.0.0. The default value will allow the Distributed Web to listen on all IPs associated with the AnthillPro server.

    • HTTP or HTTPS for Distributed Web Interface. Determine if the Distributed Web should use HTTPS or not. Enter Y to use HTTPS, or N to use HTTP. Default is N.

      • Distributed Web port for web connections. If using HTTPS, enter the port on which the Distributed Web will listen for web connections. Default is 8443.

    • Distributed Web port for web connections. Enter the port on which the Distributed Web interface will listen for web connections. Default is 8080.

  6. Start the Distributed Web Interface.

    • Open the Distributed Web interface's '/bin' directory.

    • Run: 'ah3web run'.

    OR:

    • Start the Distributed Web interface in the background. Run: 'ah3web start'.

  7. Retrieve the Distributed Web Interface license.

  8. Go to the AnthillPro server UI. Navigate to System > Licenses and paste the license in the Upload New License text field. Click Upload then Done.

  9. See Install Agent Relay (Linux/Unix) and Managing Distributed Servers.

Install Agent Relay (Linux/Unix)

If Agent communication is routed through the relay proxy, the Relay must be installed before installing the agents that will use it.

Before installing the Agent Relay, make sure the AnthillPro server is installed (see Linux/Unix Server Installation from tar.gz File) and that the license has been uploaded to the AnthillPro server (see Upload Distributed Servers License).

  1. Download the anthill3-agent-relay-<version>.tar.gz file.

  2. Expand the file to create the anthill3-agent-relay directory.

  3. Open the anthill3-agent-relay directory.

  4. Run the install script install.sh.

  5. Provide the following:

    • Location of Agent Relay. Give the directory where the Agent Relay should be installed. Default is /opt/anthill3/relay. If the directory does not already exist, enter Y to have the installer create it. Default is Y.

    • Java home. Enter the Java home used to run the Distributed Web interface. The installer will attempt to find it, or use the JAVA_HOME variable. If not found, you will need to enter it here.

    • Name. Give a name for the relay. Each Agent Relay should be given a unique, meaningful name. Default name is agent-relay.

    • Agent Relay IP or host name. Enter the IP or hostname the Agent Relay will listen on. Default is 0.0.0.0. The default value will allow the Agent Relay to listen on all IPs associated with the AnthillPro server.

    • Port Relay listens on for HTTP requests. Enter the port on which the Agent Relay should listen for HTTP requests coming from the agent(s). Default is 20080.

    • Port Relay uses for communication. Enter the port on which the Agent Relay will use for communication with the agent. Default is 7916.

    • AnthillPro server IP or host name. Enter the IP or host name of the AnthillPro server. This is the host, or IP, on which the Agent Relay can contact the main AnthillPro server. To determine the AnthillPro server IP or host name, go to: AnthillPro UI > System > Server Settings.

    • AnthillPro server communication port. Enter the port which the AnthillPro server uses for communication. If you used the default value during server installation, use 7915. If the AnthillPro server uses a different port, go to the AnthillPro server's /conf/server/ directory and open the install.properties file in a text editor. The port is listed in the install.server.jms.port= property.

    • Secure communication. Determine if using secure communication between the server, the relay, and the agents. To use secure connection, enter Y. Default is N.

      • Mutual authentication. If using secure communication, determine if mutual authentication is required. To require mutual authentication, enter Y. Default is N.

  6. Start the Agent Relay.

    • To start the Agent Relay in a new shell, go to the Agent Relay's /bin directory and run ah3relay start.

    Or:

    • To start the Agent Relay from the command line, run ah3relay run.

  7. See Install the Agent with Relay (Linux/Unix).

Install the Agent with Relay (Linux/Unix)

Make sure the AnthillPro server and Distributed Web Interface are installed. See Linux/Unix Server Installation from tar.gz File and Install Distributed Web Interface (Linux/Unix).

If you are not using the Agent Relay, follow the agent installation instructions found in Installing AnthillPro.

  1. Download the anthill3-<version>.tar.gz file. If you only installing agents, you can download the anthill3-agent-<version>.tar.gz file, which is much smaller.

  2. Open a UNIX shell to the directory containing the above downloaded file.

  3. Extract the downloaded file. Type: tar -zxf anthill3-<version>.tar.gz.

    • On some installations of Solaris and HP-UX the default tar command will not properly handle our tar files. You may need to use \ install GNU tar.

      When installing AnthillPro on Solaris, it is recommended to use korn shell (ksh).

  4. cd anthill3-install.

  5. Run the install script: ./install-agent.sh.

  6. Provide the following information:

    • Directory where the AnthillPro agent should be installed. For example: /opt/anthill3/agent . To have the installer create the directory, enter Y.

    • Java home. Enter the Java home used to run the Agent. The installer will attempt to find it, or use the JAVA_HOME variable. If not found, you will need to enter it here.

    • Relay connection. Enter Y. Before continuing, make sure the Agent Relay is already installed (separate download). See Install Agent Relay (Linux/Unix).

    • Host name or address of the Agent Relay. Default is localhost.

    • Port which the Agent Relay will use for communication. Default is 7916.

    • Determine if communication should be secured using SSL. Default is N.

      When using SSL, you need to turn it on for both the server and the agent -- otherwise the agents will not be able to connect to the server. If you are using the agent relay, ensure that SSL is turned on for all three components: server, agent, and agent relay. This rule also applies if using mutual authentication.

      • If using SSL, determine if mutual authentication should be used. Default is N.

    • HTTP port the Agent Relay will use for web requests. Default is 20080.

  7. Enter name of agent.

To run the AnthillPro agent, follow the steps below:

  1. Open a UNIX shell to the directory where you installed the agent. If you took our suggestion, then this is: /opt/anthill3/agent.

  2. cd bin.

  3. Run the script: ./ah3agent start.

See Distributed Servers and Agent Configuration.

Distributed Servers and Agent Configuration

Configure the Agent to use the Distributed Web Interface for Codestation caching. Follow the instructions given in Configure Agent(s). From the Preferred Server drop-down menu, select the Distributed Server you want this agent to receive work from.

Agents that are installed on the same LAN as the distributed server will maximize server performance. See Managing Distributed Servers.

Using SSL with Distributed Web Interface

It is possible to configure the AnthillPro server to use SSL with the Distributed Web Interface. To do so, you will need to import an existing certificate and switch to https. Before you begin, make sure AnthillPro is not running any jobs (you can do this on the Current Activity page). The ports listed in the examples may be different than those used by your AnthillPro system.

  1. Shutdown the AnthillPro server and backup the following files:

    • conf/server/installed.properties

    • opt/tomcat/conf/server.xml

    • opt/tomcat/webapps/ROOT/WEB-INF/web.xml

  2. Edit conf/server/installed.properties file:

    • Change: install.server.web.always.secure=Y

      Add: install.server.web.https.port=8443

  3. Edit opt/tomcat/conf/server.xml file:

    • Change: port 8080 connector

      Add: redirectPort="8443"

      Add a new connector:

      <Connector port="8443"
    address="0.0.0.0"
    maxThreads="150"
    minSpareThreads="25"
    enableLookups="false"
    acceptCount="100"
    debug="0"
    connectionTimeout="20000"
    disableUploadTimeout="true"
    algorithm="SunX509"
    scheme="https"
    secure="true"
    clientAuth="false"
    sslProtocol="TLS"
    keystoreFile="conf/tomcat.keystore"
    keystorePass="changeit" />

  4. Edit opt/tomcat/webapps/ROOT/WEB-INF/web.xml file:

    • Replace: <!-- security-constraints --> with:

      <security-constraint>
  <web-resource-collection>
    <web-resource-name>
      Tools
    </web-resource-name>
    <url-pattern>/tools/*</url-pattern>
  </web-resource-collection>
</security-constraint>

<security-constraint>
  <web-resource-collection>
    <web-resource-name>
      Automatic SSL Forwarding
    </web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>
      CONFIDENTIAL
    </transport-guarantee>
  </user-data-constraint>
</security-constraint>

  5. To import certificate go to opt/tomcat/conf directory and run the following command (assuming Java /bin directory is on your path):

    • keytool -import -noprompt -alias tomcat -file path_to_certificate_file.crt -storepass "changeit" -keystore tomcat.keystore

  6. Start server.