TeamCity Data Directory

Last modified: 20 April 2023

"TeamCity Data Directory" is the directory on the file system used by TeamCity server to store configuration settings, build results and current operation files. It is usually named .BuildServer. The config subdirectory 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). See more on the directory structure data_directory_structure. You can also review information on Manual Backup and Restore to get more understanding on what data is stored in the database and what on the file system.

On a running TeamCity server, the currently used data directory can be looked up on the Administration > Server Configuration page. The directory is also logged into logs/teamcity-server.log on server startup (look for "TeamCity data directory:" line).

By default, the <TeamCity data directory> is placed in the user's home directory (e.g. it is $HOME/.BuildServer under Linux and C:\Documents and Settings\<user_name>\.BuildServer) under Windows. Alternatively, you can define this directory in one of the following ways:

  • in the TEAMCITY_DATA_PATH environment variable. This is the recommended approach unless you run TeamCity as Windows service. Please note that teamcity.data.path JVM system property overrides the value set by the environment variable.

  • as a web server (Tomcat) system JVM property teamcity.data.path (see Configuring TeamCity Server Startup Properties.

The TeamCity Windows installer configures the TeamCity data directory during one of the installation steps and stores it in the Tomcat service settings.

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. Please also refer to Clean-Up section to configure automatic cleaning of older builds.

Please note that it is not a good idea to place TeamCity data directory to a network folder. Such folders may become inaccessible if network failure occurs and TeamCity may decide that projects are deleted and unload them. If you really need to place data directory to such folder, we strongly recommend to disable files modifications monitoring by launching TeamCity with special Configuring TeamCity Server Startup Properties: teamcity.configuration.checkInterval. Set this property to -1 to disable changes checking. Positive value defines changes checking interval in seconds.

Structure of TeamCity Data Directory



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

    • _trash — backup copies of deleted projects, it's OK to delete them manually.

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

    • _loggingTeamCity Server Logs configuration files

    • <project name> — configuration settings specific to a particular project

      • project-config.xml — main project configuration, contains configurations of a project's Build Configuration

      • plugin-settings.xml — auxiliary project settings, like custom project tabs content

      • project-config.xml.N and plugin-settings.xml.N--- backup copies of corresponding files created when a project's configuration is changed via web UI

      • <buildConfigurationID>.buildNumbers.properties — build number settings for a build configuration with internal id "buildConfigurationID"

    • main-config.xml — server-wide configuration settings

    • database.properties — database connection settings, see more at Setting up an External Database

    • vcs-roots.xml — VCS roots configurations file (both shared and not shared)

    • roles-config.xml — roles-permissions assignment file

    • license.keys — a file which stores the license keys entered into TeamCity.

    • change-viewers.propertiesExternal Changes Viewer configuration properties

    • internal.properties — file for specifying various Configuring TeamCity Server Startup Properties

    • ldap-config.propertiesLDAP Integration configuration properties

    • ntlm-config.propertiesConfiguring 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

    • 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 TeamCity start. The structure of a plugin is described in Plugins Packaging.

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

  • .BuildServer/system — a directory where build results data are stored, namely:

    • artifacts — a directory where the builds' artifacts are stored. The format of artifact storage is <project name>/<build configuration name>/<internal_build_id>

    • messages — a directory where Build Log are stored in internal format. Please note that test output and test failure details are stored in the build log files on disk. Build with internal id "xxxx" stores it's log in CHyy/xxxx.* file, where "yy" are the last two digits of xxxx.

    • 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.

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

    • 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. However, it's 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 in the config directory can be edited manually. They can even be edited without stopping the server. 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.

.dist Template Configuration Files



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

  • Together with the file (suppose named fileName) 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 they can be updated.

XML Structure and References



If you plan to modify configuration manually please note that there are interlinking entries that link by id. Examples of such entries are build configuration -> VCS roots links and VCS root -> project links. All the entries of the same type must have unique ids. 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.