Skip to end of metadata
Go to start of metadata
You are viewing documentation of TeamCity 4.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.

Table of Contents

We strongly urge you to make the backup of TeamCity data before making any upgrade. Please note that TeamCity server does not support downgrading.

This page covers:

Server Backup


Before performing the backup procedures, you need to stop the TeamCity server.

The following is needed to be backed up:

  1. <TeamCity data directory>
    You may refer to TeamCity Data Directory section on the directory structure. If necessary, you can exclude parts of the directory from backup to save space — you will lose only the excluded data. You may safely exclude "system/caches" directory from backup — the necessary data will be rebuild from scratch on TeamCity startup.

    Please note that you need to always back up the <TeamCity data directory>/system/version.dat file, and ensure it is saved/restored in sync with other data files and the database data.

    If you decide to skip data backup under <TeamCity data directory>/system directory, make sure you note the most recent files in each of artifacts, messages and changes subdirectories and save this information. It will be needed if you decide to restore the database backup with TeamCity Data Directory corresponding to a newer state then the database.
    The <TeamCity data directory>/system/buildserver.* files store HSQLDB data. You should back them up if you use HSQLDB (the default setting).
  2. Database data
    Database stores all information on the build results (except for artifacts and build logs), VCS changes, pinned builds, agents, build queue, user accounts, etc.
    • If you use HSQLDB, internal database (default setting, not recommended for production), the database is stored in the files residing directly in <TeamCity data directory>/system folder. All files from the directory can be backed up. Or refer to the HSQLDB backup notes.
    • If you use external database, please back up your database schema used by TeamCity.

      External database connection settings are specified in the <TeamCity data directory>/config/ file. See also corresponding installation section.

  3. Application files
    You do not need to back up TeamCity application directory (web server alone with the web application), provided you still have original distribution package and you didn't:
    • place any custom libraries for TeamCity to use
    • install any non-default TeamCity plugins
    • make any startup script/configuration changes
      If you feel you need to back up the application files:
    • If you use non-war distribution: back up everything under <TeamCity home directory> except for temp and work directories.
    • If you use war distribution, pursue the backup procedure of the servlet container used.
  4. Log files
    If you need TeamCity log files (which are mainly used for problem solving or debug purposes), back up <TeamCity home directory>/logs directory.

    You may also want to back up TeamCity Windows Service settings, if they were modified.

Restoring the Server backup


You should always restore both data in <TeamCity data directory> and data in the database. Both database and the directory should be backed up/restored in sync.

TeamCity Data Directory restoring

You can simply put the previously backed up files back to their original places. However, it is important that no extra files are present when restoring the backup.
The simplest way to achieve this is to restore the backup over a clean installation of TeamCity. If this is not possible, please make sure the files created after the backup was done are cleared. Especially the newly appeared files under the artifacts, messages, changes directories under <TeamCity data directory>/system.

Restoring to a new server

If you want to run a copy of the server, make sure the server use distinct data directories and databases. For external database make sure you modify settings in <TeamCity data directory>/config/ file to point to another database.

Build Agent's Data Backup

  1. Build Agent configuration
    Back up the <Agent Home Directory>/conf/ file.
    You may also wish to back up any other configuration files changed (Build Agent configuration is specified in <Agent Home Directory>/conf and <Agent Home Directory>/launcher/conf directories).
  2. Log files
    If you need Build Agent log files (mainly used for problem solving or debug purposes), back up <Agent Home Directory>/logs directory.

    You may also wish to back up Build Agent Windows Service settings, if they were modified.