Icon

You are viewing the documentation of TeamCity 9.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-49892

...

  • An agent should be able to open HTTP connections to the server using the server address specified in the serverUrl property (usually the same URL as server web UI)
  • Unless the unidirectional agent-to-server connection supported since TeamCity 9.1 is configured, the server should be able to open HTTP connections to the agent. The port is determined using the ownPort property of the buildAgent.properties file as the starting port (9090 by default), 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

...

  • open outbound HTTP connections to the server address (the same address you use in the browser to view the TeamCity UI)
  • unless the unidirectional agent-to-server connection supported since TeamCity 9.1 is configured, accept inbound HTTP connections from the server to the port specified as the ownPort property in the buildAgent.properties file (9090 by default). Please ensure that any firewalls installed on the 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).

...

  • 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 article)
  • Debug programs (for take process dump functionality to work)
  • Reboot the machine (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

...

Since TeamCity 9.1, it is sufficient to set up only one connection, enabling unidirectional communication from the agent to the server.

...

  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.6+ 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 setup 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. 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 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

...

Note

You can configure to start build agent on system boot, and place plist file to /Library/LaunchDaemons directory. But in this case there could be some troubles with running GUI tests, and with build agent auto-upgrade. So we do not recommend this approach.

See this external posting for some more details on LaunchDaemons.

...

  • If the appropriate Java version is detected on the agent, the agent page provides an action to upgrade the Java automatically. Upon the action invocation, the agent will restart using another JVM installation.
  • (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 and restart the agent - it should then detect it and provide an action to use a newer Java in web UI.
  • Install a required Java on the agent and configure agent to use it.

Installing Several Build Agents on the Same Machine

...

If you want to install additional agents as services under Windows, do not opt for service installation during the installer wizard or install manually (see also a feature request), then
modify the <agent>\launcher\conf\wrapper.conf file so that the wrapper.console.title, wrapper.ntservice.name, wrapper.ntservice.displayname and wrapper.ntservice.description properties have unique values within the computer. Then run the <agent>\bin\service.install.bat script under a user with sufficient privileges to register the new agent service. Make sure to start the agent for the first time only after it is configured as described.
See above for the service start/stop instructions.

...