Setting up and Running Additional Build Agents

Before you can start customizing projects and creating build configurations, you need to configure build agents.

Installing Additional Build Agents

You can install an additional build agent using any of the following installation options available:

• installingBuildAgentsJavaWebStart

• installingBuildAgentsViaMSWindowsInstaller

• installingBuildAgentsZip

When the newly installed agent connects to the server for the first time, it appears on the Unauthorized agents tab under Agents, where administrators can authorize it. This will connect the agent to the server for the first time.

Installing via Java Web Start

1. Make sure JDK 1.5+ is properly installed on the computer.

2. On the agent computer, set up the JAVA_HOME environment variable to point to the JDK 1.5+ installation directory.

3. Navigate to the Agents tab in the TeamCity web UI.

4. Click the "Install Build Agents" link and then click "Via Java Web Start".

5. Follow the instructions.

Installing via a MS Windows installer

1. Navigate to the Agents tab in the TeamCity web UI.

2. Click the "Install Build Agents" link and then click MS Windows Installer link to download the installer.

3. Run the agentInstaller.exe Windows Installer and follow the installation instructions.

Installing via ZIP File

1. In TeamCity Web UI, navigate to the Agents tab

2. Click the Install Build Agents link and then click download zip file

3. Unzip the downloaded file into the desired directory.

4. Make sure that you have a JDK or JRE installed (You will need JDK (not JRE) for some build runners like Ipr runner, Inspections, and Duplicates). Please ensure that the JRE_HOME or JAVA_HOME environment variables are set (pointing to the installed JRE or JDK directory respectively) for the shell in which the agent will be started.

5. Navigate to the <installation path>\conf directory, locate the file called buildAgent.dist.properties and rename it to buildAgent.properties.

6. Edit the buildAgent.properties file to specify the TeamCity server URL and the name of the agent. Please refer to Build Agent Configuration section for more details on agent configuration

7. Under Linux, you may need to give execution permissions to the bin/agent.sh shell script.

Starting the Build Agent

To start the agent manually, run the following script:

• for Windows: <installation path>\bin\agent.bat start

• for Linux and MacOS X: <installation path>\bin\agent.sh start

Stopping the Build Agent

To stop the agent manually, run the <Agent home>\agent script with a stop parameter.

Use stop to request stopping after current build finished. Use stop force to request immediate stop (if a build is running on the agent, it will be stopped abruptly (canceled)) Under Linux, you have one more option top use: stop kill to kill the agent process.

If the agent runs with a console attached, you may also press Ctrl+C in the console to stop the agent (if a build is running it will be canceled).

Installing and Running a Build Agent as a Windows Service

In Windows, you may want to use the build agent Windows service to allow the build agent to run without any user logged on.

To install the service:

1. Make sure there is no TeamCity Build Agent Service <build number> or agentd service already installed, if installed, uninstall the agent.

2. Check wrapper.java.command property in <agent home>\launcher\conf\wrapper.conf file to contain valid path to Java executable in the JDK installation directory. You can use wrapper.java.command=../jre/bin/java for agent installed with Windows distribution.

3. Run the <agent home>/bin/service.install.bat file.

To start the service:

• Run <agent home>/bin/service.start.bat

To stop the service:

• Run <agent home>/bin/service.stop.bat

The service wrapper allows to change agent JVM parameters via the configuration file: <agent home>\launcher\conf\wrapper.conf

While using net.exe utility, use TCBuildAgent name. For example:

net start TCBuildAgent

Using LaunchDaemons Startup Files on MacOSx

For MacOSx, TeamCity provides ability to load a build agent automatically at the system startup using LaunchDaemons plist file.

To use LaunchDaemons plist file:

1. Install build agent on Mac either via buildAgent.zip or via Java web-start

2. Prepare conf/buildAgent.properties file

3. Load build agent to LaunchDaemon via command: sh buildAgent/bin/mac.launchd.sh load

4. Copy buildAgent/bin/jetbrains.teamcity.BuildAgent.plist to /Library/LaunchDaemons directory for automatic startup (you may need to create this directory, if it doesn't exists)

5. To stop build agent, run the following command: sh buildAgent/bin/mac.launchd.sh unload

Installing Several Build Agents on the Same Machine

Several agents can be installed on a single machine. They function as separate agents and TeamCity works with them as different agents, not utilizing the fact that they share the same machine. After installing one agent you can install additional one, providing the following conditions are met:

• the agents are installed in the separate directories

• they have distinctive work and temp directories

• buildAgent.properties is Build Agent Configuration to have different values for name and ownPort properties

Make sure, there are no build configurations that have absolute Build Checkout Directory specified (alternatively, make sure such build configurations have "Clean Checkout" option enabled and they cannot be run in parallel).

Under Windows, to install additional agents as services, modify <agent>\launcher\conf\wrapper.conf to change wrapper.console.title, wrapper.ntservice.name, wrapper.ntservice.displayname and wrapper.ntservice.description properties to have distinct name within the computer.