Server Administrator Guide
This section focuses on server administration: installing TeamCity server and agents, configuring multi-node setup, setting up user permissions, and more.
The TeamCity build system comprises a server and build agents. The following sections outline the key information about each of these components.
TeamCity server does not run either builds or tests: the server's job is to monitor all the connected build agents, distribute queued builds to the agents based on compatibility requirements, and report the results.
All information on the build results (build history and all the build-associated data except for artifacts and build logs), VCS changes, agents, build queue, user accounts, user permissions, and so on, are stored in a database that can be hosted on a separate machine.
TeamCity server can occupy one machine or include multiple distributed nodes for an improved stability and performance.
Similarly to agents, a server can run as a Docker container rather than a permanently installed software.
An agent is a piece of software that typically checks out the source code, downloads artifacts of other builds and runs the build process. It is installed and configured separately from the TeamCity server.
Agents can be installed on both physical and cloud-hosted virtual machines.
note
TeamCity agents can be installed on the same machine as TeamCity server. However, for production purposes, we recommend installing them on different machines for a number of reasons, the server performance being the most important.
An agent can run builds of any compatible build configuration. Each agent can have a unique environment: architecture, operating system, installed tools, and so on. These properties define which builds an agent can run.
An agent can run a single build at a time. The number of agents basically limits the number of parallel builds and environments in which your build processes are run.
To ensure the smooth agent operation, you need to periodically update core software and tools of agents installed from executable files or archives. For example, after you upgrade a TeamCity server to a newer version, all cloud agents started from an existing VM image will need some time to update (this happens automatically but delays the moment your queued builds can start). To ensure your agents are always running the latest software, run them as Docker containers instead.
Since builds can run inside Docker or Podman containers, the agent machine's OS alone does not limit the agent-project compatibility. In other words, you can run Linux-specific tasks on Windows agents and vice versa.
Related article: Install and Start TeamCity Agents
TeamCity stores build history, users, build results, and some runtime data in a built-in SQL database.
The currently used database is shown on the Administration | Global Settings page. It is also mentioned in teamcity-server.log on the server startup. HSQL* means that the internal database is in use. For stability and security, it is recommended to migrate from the default HSQL to an external database located on a separate machine.
tip
If you have been evaluating TeamCity with the internal database and want to copy the data from it, read how to migrate to an external database.
See this section for more information: Set up External Database
The TeamCity server can be configured to use multiple nodes (or servers) for high availability and flexible load distribution. It is possible to set up a cluster of TeamCity nodes, where each node is responsible for different tasks, like processing data from builds or collecting changes from VCS repositories. Or, to keep one main node that does all the work and a secondary node that provides a read-only interface. In case the main node goes down, all data processing can be switched to the secondary node with minimum downtime.
See this article to learn more: Multinode Setup for High Availability
TeamCity provides a variety of diagnostic tools and indicators to monitor and troubleshoot the server, including detailed server logs, health reports, and resource monitors. These tools make it easier to identify and investigate problems and, if needed, report issues on your server.
For more information, refer to these topics: TeamCity Monitoring and Diagnostics, Build Agents Configuration and Maintenance
A CI/CD server is the backbone of modern software development, holding the keys to your internal processes, user credentials, and integrations with external services like AWS build agents, Google Cloud artifact storage, or HashiCorp Vault. A single security lapse can expose critical infrastructure, making robust protection essential. See the following articles to learn more about basic layers of TeamCity protection:
warning
For security reasons, we always recommend installing minor bug-fix updates that are typically released monthly. These updates ship vulnerability patches, preventing potential security-related accidents. See our security bulletin to learn more.