Before you can start customizing projects and creating build configurations, you need to configure build agents.
tip
If you install TeamCity bundled with a Tomcat servlet container, or opt to install an agent for Windows, both the server and one build agent are installed. This is not a recommended setup for production purposes, since the build procedure can slow down the responsiveness of the web UI and overall TeamCity server functioning. If you need more build agents, perform the procedure described below.
Before the installation, please review Known Issues section.
Necessary OS and environment permissions
Please note that in order to run a TeamCity build agent, user account that is running the agent should have the privileges described below.
Network
Agent should be able to open HTTP connections to the server (to the same URL as server web UI)
Server should be able to open HTTP connections to the agent. The port is determined by "ownPort" property of buildAgent.properties file (9090 by default) and the following hosts are tried:
host specified in the "ownAddress" property of buildAgent.properties file (if any)
source host of the request received by the server when agent establishes connection to the server
address of the network interfaces on the agent machine
If the agent is behind NAT and cannot be accessed by any of addresses of agent machine network interfaces, please specify ownAddress in the agent config.
Common
agent process (java) should be able to open outbound HTTP connections to the server address (the same address you use in the browser to view TeamCity UI) and accept inbound HTTP connections from the server to the port specified as "ownPort" property in "<TeamCity agent home>/conf/buildAgent.properties" file (9090 by default). Please ensure that any firewalls installed on agent, server machine or in the network and network configuration comply with these requirements.
have full permissions (read/write/delete) to the following directories: <agent home> (necessary for automatic agent upgrade), <agent work>, and <agent temp>.
launch processes (to run builds).
Windows
Log on as a service (to run as Windows service)
Start/Stop service (to run as Windows service, necessary for agent upgrade to work)
Debug programs (for take process dump functionality to work)
For granting necessary permissions for unprivileged users, see Microsoft SubInACL utility. For example, to grant Start/Stop rights you might need to execute subinacl.exe /service browser /grant=<login name>=PTO command.
Linux
user should be able to run shutdown command (for agent machine reboot functionality and machine shutdown functionality when running in Amazon EC2)
Build-related Permissions The build process is launched by TeamCity agent and thus shares the environment and is executed under the same OS user that TeamCity agent runs under. Please ensure that TeamCity agent is configured accordingly. See Known Issues for related Windows Service Limitations.
Server-Agent Data Transfers
note
Please be sure to read through this section is you plan to deploy agent and server into non-secure network environments.
During TeamCity operations, both server establishes connections to the agents and agents establish connections to the server.
Please note that by default, these connections are not secured and thus are exposing possibly sensitive data to any third party that can listen to the traffic between the server and the agents. Moreover, since the agent and server can send "commands" to each other an attacker that can send HTTP requests and capture responses can in theory trick agent into executing arbitrary command and perform other actions with a security impact.
It is recommended to deploy agents and the server into a secure environment and use plain HTTP for agents-to-server communications as this reduces transfer overhead.
It is possible to setup a server to be available via HTTPS protocol, so all the data traveling through the connections established from an agent to the server (incl. download of build's sources, artifacts of builds, build progress messages and build log) can be secured. See Using HTTPS to access TeamCity server for configuration details.
However, the data that is transferred via the connections established by the server to agents (build configuration settings (all the settings configured on the web UI including VCS root data) is passed via unsecured HTTP connection. For the time being TeamCity does not provide internal means to secure this data transfers (see/vote for TW-5815). If you want to secure the data you need to establish appropriate network security configurations like VPN connections between agent and server machines.
Installing Procedure
You can install an additional build agent using any of the following installation options available:
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.
note
Agents will not run builds until they are authorized in the TeamCity web UI. The agent running on the same computer as the server is authorized by default.
Installing via Java Web Start
Make sure JDK 1.5+ is properly installed on the computer.
On the agent computer, set up the JAVA_HOME environment variable to point to the JDK 1.5+ installation directory.
Navigate to the Agents tab in the TeamCity web UI.
Click the "Install Build Agents" link and then click "Via Java Web Start".
Follow the instructions.
tip
You can install the build agent Windows service during the installation process or buildAgentsWindowsService.
Installing via a MS Windows installer
Navigate to the Agents tab in the TeamCity web UI.
Click the "Install Build Agents" link and then click MS Windows Installer link to download the installer.
Run the agentInstaller.exe Windows Installer and follow the installation instructions.
note
Please ensure the user under whom the agent service is running has appropriate agent_permissions
Installing via ZIP File
In TeamCity Web UI, navigate to the Agents tab
Click the Install Build Agents link and then click download zip file
Unzip the downloaded file into the desired directory.
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.
Navigate to the <installation path>\conf directory, locate the file called buildAgent.dist.properties and rename it to buildAgent.properties.
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
Under Linux, you may need to give execution permissions to the bin/agent.sh shell script.
tip
On Windows you may also want to install the buildAgentsWindowsService instead of manual agent startup.
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
note
If you're running build agent on MacOS X and you're going to run Inspection builds, you may need to use the StartupItemContext utility:
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.
tip
Since version 1.2, Build Agents are using a new Windows Service Library: Java Service Wrapper. The old service name, agentd, is no longer used in fresh installations. Agents that were already installed will continue to use old service until explicit installation. (Upgrade)
To install the service:
Make sure there is no TeamCity Build Agent Service <build number> or agentd service already installed, if installed, uninstall the agent.
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.
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
tip
The agent process name is TeamCityAgentService-windows-x86-32.exe.
While using net.exe utility, use TCBuildAgent name. For example:
net start TCBuildAgent
warning
To run builds, the build agent should be started under a user with enough permissions for performing a build. By default, Windows service in started under SYSTEM ACCOUNT. To change it, use the Services applet (Control Panel|Administrative Tools|Services)
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 LaunchDaemonsplistfile:
Install build agent on Mac either via buildAgent.zip or via Java web-start
Prepare conf/buildAgent.properties file
Fix launcher permissions, if needed: chmod +x buildAgent/launcher/bin/*
Load build agent to LaunchDaemon via command: sh buildAgent/bin/mac.launchd.sh load
note
You have to wait several minutes for the build agent to auto-upgrade from the TeamCity server.
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)
To stop build agent, run the following command: sh buildAgent/bin/mac.launchd.sh unload
If you need to configure TeamCity agent environment you can change <TeamCity Agent Home>/launcher/conf/wrapper.conf (JSW configuration). For example, to make the agent see Mono installed using MacPorts on Mac OS X agent you will need to add the following line:
Installing Several Build Agents on the Same Machine
In general, the installation procedure is the same, however, before installing additional agents on the same machine, make sure to familiarize yourself with How To....