View Source

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 [backup|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 {{}} Tomcat web server service [JVM property|Configuring TeamCity Server Startup Properties#JVMPropertiesService]

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

h3. Recommendations as to choosing Data Directory Location
Note that the {{system}} directory stores all the [artifacts|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|].

Please note that it is not a good idea to place the entire 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 [internal property|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.

h2. 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_ --- [internal server 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 Configurations|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 [internal TeamCity properties|Configuring TeamCity Server Startup Properties]. Is not present by default and should be created if necessary.
-- _ldap-config.properties_ --- [LDAP authentication|LDAP Integration] configuration properties
-- _ntlm-config.properties_ --- [Windows domain authentication|Configuring Authentication Settings#Windows Domain Authentication] 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 [below|#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.

- {anchor:systemDir}*_.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.
-- {anchor:artifacts} _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 [hidden artifacts|Build Artifact#Hidden Artifacts]. 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.)
-- {anchor:rawLogs} _messages_ --- a directory where [build logs|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 [remote run|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 [web UI|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 [database drivers|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.

h2. 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 [back up|TeamCity Data Backup] your data before making any changes.

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

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

{color:#003366}*See also:*{color}
*Installation and Upgrade*: [TeamCity Data Backup]