Icon

You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.1 documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: related to https://youtrack.jetbrains.com/issue/TW-56205, minor edits

...

Before you can start customizing projects and creating build configurations, you need to configure build agents. Please review the agent-server communication and Prerequisites section before proceeding with agent installation. 

...

Expand
titleLegacy bidirectional communication notes
For the fallback bidirectional communication, in addition for the agent to server connections, the server must be able to open HTTP connections to the agent. The agent port is determined using the ownPort property of the buildAgent.properties file as the starting port (9090 by default, next port is used if the specified port is busy), and the following IP addresses are tried:
  • the address specified in the ownAddress property of the buildAgent.properties file (if any)
  • the source IP of the HTTP request received by the server when the agent establishes a connection to the server. If a proxying server is used, it must be correctly configured.
  • the addresses of the network interfaces on the agent machine

If the agent is behind NAT and cannot be accessed by any of addresses of the agent machine network interfaces, please specify the ownAddress property in the buildAgent.properties file.

Please ensure that any firewalls installed on the agent, server machine, or in the network and network configuration comply with these requirements.

...

  • Log on as a service (to run as Windows service)
  • Start/Stop service (to run as Windows service, necessary for the agent upgrade to work, see also Microsoft KB articleMicrosoft KB article)
  • Debug programs (required for take process dump functionality to work)
  • Reboot the machine (for required for agent reboot functionality to work

  • To be able to monitor performance of a build agent run as a Windows service, the user starting the agent must be a member of the Performance Monitor Users group

...

By default (since TeamCity 10), a TeamCity agent connects to the TeamCity server via the URL configured as the "serverUrl" agent property. This is called unidirectional agent-to-server connection. In rare cases, TeamCity may switch to old, bidirectional communication which also requires establishing a connection from the server to the agents.
Unless security in transfer between the agent and the server is important, it is recommended to deploy agents and the server into a secure environment and configure agents to use plain HTTP URL for the server as this reduces transfer overhead.

...

If for some reason the polling protocol cannot be used, TeamCity switches to the fallback bidirectional communication via xml-rpc (the default prior to TeamCity 10).

...

  1. Install a build agent using any of the following options:
  2. After installation, configure the agent specifying its name and the address of the TeamCity server in the conf/buildAgent.properties file.
  3. Start the agent. If the agent does not seem to run correctly, please check the agent logs.

...

  1. In the TeamCity Web UI, navigate to the Agents tab.
  2. Click the Install Build Agents link and select MS Windows Installer to download the installer.
  3. Run the agentInstaller.exe Windows Installer and follow the installation instructions.

    Note

    Please ensure that the user account used to run the agent service has appropriate permissions

Anchor
installingBuildAgentsZip
installingBuildAgentsZip

...

  1. Make sure a JDK (JRE) 1.8 (versions 1.6-1.8 are supported, but 1.8 is recommended)is properly installed on the agent computer.
  2. On the agent computer, make sure the JRE_HOME or JAVA_HOME environment variables are set (pointing to the installed JRE or JDK directory respectively).
  3. In the TeamCity Web UI, navigate to the Agents tab.
  4. Click the Install Build Agents link and select Zip file distribution to download the archive.
  5. Unzip the downloaded file into the desired directory.
  6. Navigate to the <installation path>\conf directory, locate the file called buildAgent.dist.properties and rename it to buildAgent.properties.
  7. 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 details on agent configuration.
  8. Under Linux, you may need to give execution permissions to the bin/agent.sh shell script.

    Info

    On Windows you may also want to install the build agent windows service instead of the manual agent startup.

...

To configure the agent to be started automatically, see the corresponding sections:
Windows
Linux : configure daemon process with agent.sh start command to start it and agent.sh stop command to stop it.
Mac OS X

Anchor
agentStop
agentStop

Anchor
agent_start_windows
agent_start_windows

...

To run agent automatically on the machine boot under Windows, you can either set up the agent to be run as a Windows service or use another way of the automatic process start.
Using the Windows service approach is the easiest way, but Windows applies some constraints to the processes run this way.
A TeamCity agent works reliably under Windows service provided all the requirements are met, but is often not the case for the build processes configured to be run on the agent.

...

Warning
titleService system account

To run builds, the build agent must be started under a user with sufficient permissions for performing a build and managing the service. By default, a Windows service is started under the SYSTEM account which is not recommended for production use due to extended permisisons the account uses. To change it, use the standard Windows Services applet (Control Panel|Administrative Tools|Services) and change the user for the TeamCity Build Agent service.

...

The following instructions can be used to install the Windows service manually (e.g. after .zip agent installation). This procedure should also be performed to create Windows services for the second and following agents on the same machine.

To install the service:

...

The user account used to run the build agent service must have enough rights to start/stop the agent service, as described above.

Automatic Agent Start under Linux

...

  • Upgrade the Java automatically: if the appropriate Java version of the same bitness as the current one is detected on the agent, the agent page provides an action to upgrade the Java automatically. Upon the action invocation, the agent process is restarted (once the agent becomes idle, i.e. finishes the current build if there is one) using the new java.

    hidden-data
    Upon the action invocation,  the path to the detected Java is saved into the conf/teamcity-agent.jvm  file,  the agent process is restarted (once the agent becomes idle, i.e. finishes the current build if there is one)  and uses the new java from the file.

  • (Windows) Since the build agent .exe installation comes bundled with the required Java, you can just reinstall the agent using the .exe installer obtained from the TeamCity server | Agents page.
  • Install a required Java on the agent into one of the standard locations, and restart the agent - the agent should then detect it and provide an action to use a newer Java in the web UI (see above).
  • Install a required Java on the agent and configure the agent to use it.

 

Note

In a rare case of updating the Java for the process that launches the TeamCity agent, use one of the options for the agent Java upgrade.
Another way for Build Agent started as a Windows service, is to stop the service, change the wrapper.java.command variable in buildAgent\launcher\conf\wrapper.conf to point to the new java.exe binary, and restart the service.

...

If you use Windows installer to install additional agents and want to run the agent as a service, you will need to perform manual steps as installing second agent as a service on the same machine is not supported by the installer: the existing service is overwritten (see also a feature request).
In order to install the second agent, it is recommended to install the second agent manually (using .zip agent distribution). You can use Windows agent installer and do not opt for service installation, but you will lose uninstall option for the initially installed agent this way.
After the second agent is installed, register a new service for it as mentioned in the section above.

Info

For step-by-step instructions on installing a second Windows agent as a service, see a related external blog post .

...