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. (See also 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 Administration | Global Settings page for a running TeamCity server instance, or in logs/teamcity-server.log file (look for "TeamCity data directory:" line on the server startup).

Please note that in this documentation and other TeamCity materials the directory is often referred to as .BuildServer. If you have another name for it, please replace ".BuildServer" with the actual name.

TeamCity Windows installer configures the TeamCity data directory during the installation steps. The default path suggested for the directory is: Since TeamCity 7.1: %ALLUSERSPROFILE%\JetBrains\TeamCity TeamCity 7.0 and previous versions: %USERPROFILE%\.BuildServer

To change the location of the TeamCity Data Directory:

• under all OS if TeamCity is run via startup script/from command line: set TEAMCITY_DATA_PATH environment variable (either system-wide or for the user under whom TeamCity will be started)

• under Windows if TeamCity is run as a service

  • since TeamCity 7.1: the same as above: set TEAMCITY_DATA_PATH environment variable as global environment variable for all users

  • for TeamCity 7.0 and previous versions: set teamcity.data.path Tomcat web server service Configuring TeamCity Server Startup Properties

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

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 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. Still under rare circumstances the data stored it 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 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

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 get more understanding on what data is stored in the database and what 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's 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.

  • <project name> — configuration settings specific to a particular project, new directories can be created provided they have mandatory nested files

    • 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.properties — External Changes Viewer configuration properties

  • internal.properties — file for specifying various Configuring TeamCity Server Startup Properties. Is not present by default and should be created if necessary.

  • 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

  • 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. 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 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 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 artifact storage is <project name>/<build configuration name>/<internal_build_id>. If necessary, the files in each build's directory can be added/removed manually - this will be reflected in 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 build will lack corresponding feature backed by the files (like displaying/using finished build parameters, coverage reports, etc.)

  • messages — a directory where Build Log are stored in internal format. Build logs store build output, test output and test failure details. Build with internal id "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 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.

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

  • 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 (unless explicitly noted). 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.