TeamCity 2020.1 Help

TeamCity Data Directory

TeamCity Data Directory is the directory on the file system used by TeamCity server to store configuration settings, build results and current operation files. The directory is the primary storage for all the configuration settings and holds the data critical to the TeamCity installation.

The build history, users and their data and some other data are stored in the database. See notes on backup for the description of the data stored in the directory and the database.

Note that in this documentation and other TeamCity materials the directory is often referred to as .BuildServer. If you have a different name for it, replace .BuildServer with the actual name.

Location of the TeamCity Data Directory

The currently used Data Directory location can be seen on the Administration | Global Settings page for a running TeamCity server instance. Clicking the Browse link opens the Administration | Global Settings | Browse Data Directory tab allowing the user to upload new or modify the existing files in the directory.

The current Data Directory location is also available in the logs/teamcity-server.log file (look for "TeamCity Data Directory:" line on the server startup).

If you are upgrading from one of the early versions of TeamCity, note that prior to TeamCity 7.1 the Data Directory could be specified in a different way than described below.

Configuring the Location

There are two ways to configure the location of the TeamCity Data Directory:

  • by selecting it in the UI form on the first server startup (only for TeamCity .tar.gz or .exe distributions). The specified Data Directory is then saved into <TeamCity home directory>/conf/ file.

  • manually, using the TEAMCITY_DATA_PATH environment variable. The variable can be either system-wide or defined for the user under whom the TeamCity server is started. After setting/changing the variable, you might need to restart the computer for the changes to take effect.

If during the first startup TeamCity finds the Data Directory location configured as the environment variable, it skips the related startup screen and uses the detected path.

If the TEAMCITY_DATA_PATH environment variable is not set and the <TeamCity home directory>/conf/ file does not define it either, the default TeamCity Data Directory location will be the user's home directory (for example, it is $HOME/.BuildServer under Linux and %USERPROFILE%.BuildServer under Windows).

Recommendations as to choosing Data Directory Location

Since the Data Directory stores all the server and configured projects settings, it is important that it is not available for reading and writing to the OS users without the corresponding level of access. See the related security notes.

By default, the system directory stores all the artifacts and build logs of the builds in the history and can be quite large, so it is recommended to place TeamCity Data Directory on a non-system disk. Refer to the Clean-Up page to configure automatic cleaning of older builds. If a single local disk cannot store all the artifacts, you can add another disk and configure multiple artifacts paths.

Note that TeamCity assumes reliable and persistent read/write access to the TeamCity Data Directory and can malfunction if the Data Directory becomes inaccessible. This malfunction can affect TeamCity operation while the directory is unavailable and may also corrupt data of the currently running builds. While TeamCity should be able to tolerate occasional Data Directory inaccessibility, under rare circumstances the data stored in the directory might still be corrupted or partially lost.

It is recommended to store <TeamCity Data Directory>/system/caches on a local disk or even a separate dedicated disk, especially if TeamCity Data Directory is located on a network storage. You can either create a symlink to the caches directory from the main directory or, since TeamCity 2020.1.1, redefine its path via the teamcity.caches.path JVM system property which can be specified in TEAMCITY_SERVER_OPTS environment variable, for instance:

TEAMCITY_SERVER_OPTS=-Dteamcity.caches.path=<path to local caches directory>

The caches directory stores local clones of the VCS repositories, and it is important to provide good performance for it. If the directory content is lost, it will be rebuilt and no data will be lost.

Structure of TeamCity Data Directory

The config subdirectory of TeamCity Data Directory contains the configuration of your TeamCity projects, and the system subdirectory contains build logs, artifacts, and database files (if internal database (HSQLDB) is used which is default). You can also review information on Manual Backup and Restore to understand better which data is stored in the database, and which is on the file system.

Direct Modifications of Configuration Files

The files under the config directory can be edited manually (unless explicitly noted). The changes will be taken into account without the server restart. TeamCity monitors these files for changes and rereads them automatically when modifications or new files are detected. Bear in mind that it is easy to break the physical or logical structure of these files, so edit them with extreme caution. Always back up your data before making any changes.

Note that the format of the files can change with newer TeamCity versions, so the files updating procedure might need adjustments after an upgrade.

The REST API has means for most common settings editing and is more stable in terms of functioning after the server upgrade.

.dist Template Configuration Files

Many configuration files meant for manual editing use the following convention:

  • Together with the file (suppose named fileName) there comes a file fileName.dist. The .dist files are meant to store default server settings, so that you can use them as a sample for fileName configuration. The .dist files should not be edited manually as they are overwritten on every server start. Also, .dist files are used during the server upgrade to determine whether the fileName files were modified by user, or the latter can be updated.

XML Structure and References

If you plan to modify the configuration manually, note that there are entries interlinked by ids. Examples of such entries are build configuration -> VCS roots links and Project -> parent project links. All the entries of the same type must have unique ids in the entire server. New entries can be added only if their ids are unique.

See also the related section on moving projects between TeamCity servers.

Last modified: 28 October 2020