Teamcity server-to-server migration

I'd like to move my Teamcity server to a new machine, going from one Linux box to another.  I'm already using an external MySQL database, so connecting the new machine to the DB once the old Teamcity instance is shut down will be simple.  My question is, rather than using maintainDB to get some of the other backup information to move over, can I simply shutdown the old instance, rsync the .BuildServer directory on the old machine to my $TEAMCITY_DATA_ROOT directory on the new server so that they are identical (including the artifacts, etc.), set up the Teamcity.war in the new Tomcat, and then fire up the new server?  I typically use the .war distribution deployed to Tomcat rather than the .tar.gz release.

In case it's important, my current data root is the default $HOME/.BuildServer and the Teamcity server is installed in $HOME/tomcat/webapps; on the new machine it will be /opt/teamcity/BuildServer and /opt/teamcity/tomcat.

I also have one additional question: I am currently using the built-in Teamcity authentication, but I would like to switch to authenticating via Active Directory.  I saw that my existing users will be dropped when I make the switch; will my role and group structures be dropped as well or will they be preserved (i.e., will I still have "Role A" or "Group 3" with existing permissions intact but without users assigned to them)?



Syncing .BuildServer and database are all you need form TeamCity perspective.
Please also make sure you transfer all the related environment like environment variables, files that are configurd in TeamCity configuration (if any), logging settings configured in Tomcat's "config" directory, etc.
Details instructions can be found in the doc.

As to switching to another authentication scheme: settings of roles and groups are preserved.


Hi, I'm scheduling a server migration of our TC installation, we have an external sql DB, will it be enough to restore a backup on the new machine and configure to connect to the current DB?


Diego Cando,

Yes, you can use a full backup to help with your migration in this way. Please see our documentation here for additional information on this process:

Additionally, it is important to keep in mind that there is some data not included in TeamCity backups. 

Here is the relevant information from

The following data is not included into backup:

  • Build artifacts (because of their size). These include build artifacts, internal NuGet feed packages, coverage report, finish build parameters, settings digest, and so on. If you need to back up the artifacts, save the contents of artifacts directories manually before restoring TeamCity data from backup.

  • For backup from the UI: running builds and build queue state. If you want to back up these, stop the TeamCity server and use the maintainDB tool.

  • TeamCity application manual customizations under <TeamCity Home>, including used server port number, which are stored in the <TeamCity Home>/conf/server.xml file.

  • TeamCity application logs (under <TeamCity Home>/logs).

  • Any manually created files under <TeamCity Data Directory> that do not fall into previously mentioned items.


Please sign in to leave a comment.