TeamCity Data Directory

This is the directory on the file system used by TeamCity to store configuration and system 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 HSQLDB is being used by default). See more on the directory structure data_directory_structure. You can also review information on TeamCity Data Backup 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 starup (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 a 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 TeamCity Startup Properties.

The TeamCity Windows installer configures the TeamCity data directory during one of the installation steps.

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 TeamCity Startup Properties. Modifying the TEAMCITY_DATA_PATH environment variable will not work in this case.

Recommendations as to choosing Data Directory Locaiton



Note that the system directory stores all the Build Artifact 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 disappear 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 TeamCity 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 — (since TeamCity 5.1) notification templates and notification configuration settings, including syndication feeds template.

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

  • email-config.xml — (until TeamCity 5.1) the e-mail notification template

  • jabber-config.xml — (until TeamCity 5.1) the Jabber notification template

  • win32-config.xml — (until TeamCity 5.1) the Windows Tray Notifier notification template

  • ide-notificator-config.xml — (until TeamCity 5.1) the IDE notification template

  • default-feed-item-template.ftl — (until TeamCity 5.1) default Syndication (RSS) feeds template

  • change-viewers.properties — External Changes Viewer configuration properties

  • internal.properties — (since TeamCity 5.1) file for specifying various TeamCity Startup Properties

  • ldap-config.properties — LDAP Integration configuration properties

  • ntlm-config.properties — 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. The files are overwritten on each server startup.

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

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

  • responsibles.xml — a file which stores the Responsibility data.

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

  • version.dat — a file which contains the internal version of the configuration files under conf and data files under system. The file should always be backed up with any other data. Please ensure it is saved/restored in sync with other data files and the database data.

• .BuildServer/backup — default directory to store backup archives created via Backup Data. 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.