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 thatteamcity.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.
tip
If you run TeamCity as Windows service installed via Installing and Configuring the TeamCity Server from the Windows executable file, you will need to modify the
teamcity.data.path
Tomcat JVM property as described in Configuring TeamCity Server Startup Properties. Modifying theTEAMCITY_DATA_PATH
environment variable will not work in this case.
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.
note
If you're using default HSQLDB database, make sure the path to this directory contains latin charachters only.
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.
_logging — TeamCity 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.properties — External Changes Viewer configuration properties
internal.properties — file for specifying various Configuring TeamCity Server Startup Properties
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. 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 filefileName.dist
..dist
files are meant to store default server settings, so that you can use them as a sample forfileName
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 thefileName
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.