Several important notes about two-node configuration:
- the server started in the build messages processor mode handles all of the data produced by running builds (build logs, artifacts, statistic values), pre-processes it and stores it in the database and on the disk
- in a two-node installation the main TeamCity server handles all other tasks: user interface, VCS-related activity, management of agents, etc.
- both the main TeamCity server and the build messages processor require access to the same data directory (which must be shared somehow if the nodes are installed on separate machines) and to the same database
- the URL where the build messages processor operates must be accessible by the agents and the main TeamCity server (occasionally the main TeamCity server also communicates with the build messages processor by HTTP)
First of all, ensure that both machines where TeamCity software will be installed can access the same TeamCity data directory in read/write mode. For large installations we recommend using NAS. It is possible to share the directory using NFS, or Windows share, although the performance of such installation can be worse.
Configure the TEAMCITY_DATA_PATH environment variable on both machines, make sure it points to the shared data directory.
On the build messages processor machine, add additional arguments to to the TEAMCITY_SERVER_OPTS environment variable:
export TEAMCITY_SERVER_OPTS=-Dteamcity.server.mode=build-messages-processor -Dteamcity.server.rootURL=<processor url> <your regular options if you have them>,
<processor url> is the URL of the build messages processor. This URL must be accessible by both the agents and main server. If you do not have an HTTP proxy installed in front of the TeamCity servlet container and you did not change the port in the servlet container during the installation, then by default this URL will be:
http://<your host name>:8111/
Startup & shutdown
Both main the main TeamCity server and build messages processor can be started / stopped using regular TeamCity scripts (
teamcity-server.bat, teamcity-server.sh) or Windows services.
The build messages processor uses the same approach to logging as the main server. You can check how the startup is doing in the
teamcity-server.log file. You can also open
<processor URL> in your browser, there you should see regular TeamCity startup screens.
Enabling Build Messages Processor
If both - the main server and build messages processor are up and running, you should see the Administration | Nodes configuration page on the main TeamCity server:
By default, the build messages processor is disabled . And and all traffic produced by running builds is still handled by the main server. Once you enable the build messages processor, all newly started builds will be routed to this node. The existing running builds will continue being executed on the main server.
On this page you can also see how many builds are currently assigned to each node. If the build messages processor is enabled, eventually all of the running builds should will be switched to this node.
The build messages processor as well as the main TeamCity server can be stopped or restarted while builds are running there. If agents can't cannot connect to the build messages processor for some time, they will re-route their data to the main server. If the main server is also unavailable either, agents will keep their data and re-send it once servers re-appear.
Both the main TeamCity server and the build messages processor must be of exactly the same version.
The To upgrade sequence is the following:
- stop the build messages processor (if you forget
- to do that, you'll be warned during upgrade)
- start upgrade on the main TeamCity server as usual
- proceed with upgrade
- check everything is ok, agents are connecting etc. (since the messages processor is not available anymore, the agents will re-route their data to the main server)
- upgrade software on the messages processor machine to the same version
- start the messages processor and check that it is connected
- using the Nodes configuration page on the main server
In order to downgrade you need toTo downgrade:
- shutdown the main server and build messages processor
- restore data from backup (only if the data format has been changed during upgrade)
- downgrade TeamCity software on the main server
- start the main TeamCity server and check that everything works
- downgrade TeamCity software on the build messages processor to the same version as the main server
- start the build messages processor
As usually with TeamCity, agents perform upgrade / downgrade automatically.
The TeamCity cleanup task is running runs on the main TeamCity server only. In a two-node configuration as well as in a single node configuration, it can work at the same time while the servers handle are handing data from the running builds.
Backup through TeamCity web interface can be done on the main TeamCity server only. Backup from the command line can be done on either the build messages processor or on the main TeamCity server.
In order to simplify these tasks, the Project Administrators Administrator role have has got a set of agent-related permissions bound to projects. For example, let's have a look at Enable / disable agents permission.
Before this EAP, if a system administrator wanted to give give the Enable / disable agents permission to a project administrator, he/she could do that globally only. After that the project administrator would be able to enable / disable all of the agents on the TeamCity server.
Now Project Administrators can be given Enable / disable agents associated with project permission in some project only. After that only the agents belonging to pools with this project only can be enabled / disabled by this project administrator.
The same applies to other agent-related permissions which can be bound to projects.