Team City, like many CI servers, supports multiple agents to offload builds. These can be a mix of Linux and Windows (and Mac?) and can have separate capabilities but the one thing that promises to make things really easy is the idea of pushing everything you need to a new agent rather than spending ages configuring it.

Of course, the truth is not quite as simple and the Team City documentation is generally overwhelming and messy and missing some vital steps!

Fortunately, some of us believe in briefer guides so here it is: adding a new windows build server as a Team City Agent.

  1. Get yourself a windows server - I used Server 2016.
  2. If you are planning to start up and destroy agents on-demand, you might want to invest in static IP addresses so that the firewall config etc. on the TC server (if relevant) doesn't need changing each time you spin the agent back up and it gets another IP address.
  3. Log in to the windows server and make sure you can access your TC server URL i.e. firewall open, https setup on Team City. This will be tested by the agent install
  4. Install the JRE minimum 1.8 on the Agent. This will change some time after April 2019 when the JRE is being ditched for packaged Java classes.
  5. Ensure that port 445 for SMB is open. You can lock this down to the TC Server IP for extra security
  6. Optionally take the windows update hit straight away!
  7. Go into TC server, Agents, Agent Push and click Install Agent
  8. Enter the destination IP/URL and login creds. You do not need to enter different ones for the service, it will run fine as Local Service.
  9. You should see a log of activity as the server attempts to install the build agent on the remote machine including any tools configured under the server->Administration->Tools
  10. Once completed, you can optionally create a profile so you can easily run the install again later.
  11. It should appear quickly under the Disconnected agents list and will show "will be upgraded" for a few minutes, at which point, it will appear in the Connected list.
  12. Note that if your new agent doesn't have various tooling installed (Node, MSBuild etc.) then it won't meet the requirements of certain builds and therefore the agent will not be used for those builds. You can see this by clicking the agent and looking under Compatible Configurations. You can unfold the links and see what dependencies are required/missing under the right-hand side.
  13. To install extra tooling, you need to login to your windows server, install the relevant tools and then restart the build agent service, which should take a couple of minutes, after which the server should show the new capabilities.
Remember that if this is your first off-server build agent, any build steps that write to the local disk will write to the agent's local disk whereas you should ideally have an "upload via sftp" or whatever to correctly send artifacts from remote agents back to your deployment server.