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 Setting up an External Database. See notes on Manual Backup and Restore for the description of the data stored in the directory and the database.

The location of the directory is set using TEAMCITY_DATA_PATH environment variable. If the variable is not set, the TeamCity Data Directory is assumed to be located in the user's home directory (e.g. it is $HOME/.BuildServer under Linux and C:\Users\<user_name>\.BuildServer under Windows).

The currently used data directory location can be seen on the Administration | Global Settings page for a running TeamCity server instance. Since TeamCity 8.1, you can use the Browse link to view the TeamCity Data Directory. Clicking the link opens the Administration | Global Settings | Browse Data Directory tab allowing the user to upload new/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).

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.

TeamCity Windows installer configures the TeamCity data directory during installation. The default path suggested for the directory is: %\ALLUSERSPROFILE%\JetBrains\TeamCity.

Specify Location of the TeamCity Data Directory

Set TEAMCITY_DATA_PATH environment variable (either system-wide or for the user under whom TeamCity will be started). You might need to restart the computer after that for the changes to take effect.

You will need to restart the TeamCity server after making changes to the setting.

If you are upgrading, please note that prior to TeamCity 7.1 the data directory might have been specified TeamCity Data Directory.

Recommendations as to choosing Data Directory Location

Note that the system directory stores all the Build Artifact 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 Clean-Up section to configure automatic cleaning of older builds.

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

We do not recommend to place the entire TeamCity data directory to a remote/network folder. If a single local disk cannot store all the data, consider placing the data directory on a local disk and mapping .BuildServer/system/artifacts to a larger disk with the help of OS-provided filesystem links. Related feature request: TW-15251.

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.

• .BuildServer/config — a directory where projects, build configurations and general server settings are stored

  • _trash — backup copies of deleted projects, it is OK to delete them manually

  • _notifications — notification templates and notification configuration settings, including syndication feeds template

  • _logging — TeamCity Server Logs configuration files, new files can be added to the directory

  • projects — a directory which contains all project-related settings. Each project has its own directory. Project hierarchy is not used and all the projects have a corresponding directory residing directly under "projects"

    • <projectID> - a directory containing all the settings of a project with the "<projectID>" id (including build configuration settings and excluding subproject settings). New directories can be created provided they have mandatory nested files. The _Root dicrectory contains settings of the Project. Whenever *.xml.N files occur under the directory, they are backup copies of corresponding files created when a project configuration is changed via the web UI. These backup copies are not used by TeamCity.

      • buildNumbers — a directory which contains <buildConfigurationID>.buildNumbers.properties files which store the current build number counter for the corresponding build configuration

      • buildTypes — a directory with <buildConfiguration or template ID>.xml files with corresponding build configuration or template settings

      • pluginData — a directory to store optional and plugin-related project-level settings. Bundled plugins settings and auxiliary project settings like custom project tabs are stored in plugin-settings.xml file in the directory

      • vcsRoots — a directory which contains project's VCS roots settings in the files _<VcsRootID>.xml project-config.xml — the project configuration file containing the project settings, such as Configuring Build Parameters and Clean-up.

–main-config.xml — server-wide configuration settings – database.properties — database connection settings, see more at Setting up an External Database – license.keys — a file which stores the license keys entered into TeamCity – change-viewers.properties — External Changes Viewer configuration properties, if available – internal.properties — file for specifying various Configuring TeamCity Server Startup Properties. It is not present by default and needs to be created if necessary – auth-config.xml — a file storing server-wide authentication-related settings – ldap-config.properties — LDAP Integration configuration properties – ntlm-config.properties — Configuring Authentication Settings configuration properties – issue-tracker.xml — issue tracker integration settings – cloud-profiles.xml — Cloud (e.g. Amazon EC2) integration settings – backup-config.xml — web UI backup configuration settings – roles-config.xml — roles-permissions assignment file – database.*.properties — default template connection settings files for different external databases – *.dtd — DTD files for the XML configuration files – *.dist — default template configuration files for the corresponding files without .dist. See distfiles.

• .BuildServer/plugins — a directory where TeamCity plugins can be stored to be loaded automatically on the TeamCity start. New plugins can be added to the directory. Existing ones can be removed while the server is not running. The structure of a plugin is described in Plugins Packaging.

  • .unpacked — directory that is created automatically to store unpacked server-side plugins. Should not be modified while the server is running. Can be safely deleted if the server is not running.

  • .tools — create this directory to centralize tools to be installed on all agents. Any folder or .zip file under this folder will be distributed to all agents and appear under Agent Home Directory folder.

• .BuildServer/system — a directory where build results data is stored. The content of the directory is generated by TeamCity and is not meant for manual editing.

  • artifacts — a directory where the builds' artifacts are stored. The format of the artifact storage is <project ID>/<build configuration name>/< >. If necessary, the files in each build's directory can be added/removed manually - this will be reflected in the corresponding build's artifacts.

    • .teamcity directory in each build's directory stores build's Build Artifact. The files can be deleted manually, if necessary, but the build will lack the corresponding feature backed by the files (like displaying/using finished build parameters, coverage reports, etc.)

  • messages — a directory where Build Log are stored in an internal format. Build logs store the build output, compilation errors, test output and test failure details. Build with Working with Build Results "xxxx" stores it's log in CHyy/xxxx.* file, where "yy" are the last two digits of xxxx. The files can be removed manually, if necessary, but corresponding builds will drop build log and failure details (as well as test failure details).

  • changes — a directory where the Personal Build changes are stored in internal format. Name of the files inside the directory contains internal personal change id. The files can be deleted manually, if necessary, but corresponding personal builds will lose personal changes in UI and when affected queued builds try to start, they fail or run without personal patch.

  • pluginData — a directory where various plugins can store their data. It is not advised to delete or modify the directory. (e.g. state of build triggers is stored in the directory)

    • audit — directory holding history of the build configuration changes and used to display diff of the changes. Also stores related data in the database.

    • repositoryStates — directory holding current state of the VCS roots. If dropped, some changes might not be detected by TeamCity (between the state last queried by TeamCity and the current state after first server start without this data.

  • caches — a directory with internal caches (of the VCS repository contents, search index, other). It can be manually deleted to clear caches: they will be restored automatically as needed. It is more safe to delete the directory while server is not running.

  • buildserver.* — a set of files pertaining to the embedded HSQLDB.

• .BuildServer/backup — default directory to store backup archives created via Creating Backup from TeamCity Web UI. The files in this directory are not used by TeamCity and can be safely removed if they were already copied for safekeeping.

• .BuildServer/lib/jdbc — directory that TeamCity uses to search for Setting up an External Database. Create the directory if necessary. TeamCity does not manage the files in the directory, it only scans it for .jar files that store the necessary driver.

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 TeamCity Data Backup your data before making any changes.

Please 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. .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 whether 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 related comment in our issue tracker on build configurations move between TeamCity servers.