TeamCity 8.0 Help

Manual Backup and Restore

Server Manual Backup

Other ways to create a backup are TeamCity Data Backup. You can use these instructions if you want fine-grained control over the backup process or need to use a specific procedure for your TeamCity backups.

The following data needs to be backed up:

TeamCity Data Directory

TeamCity Data Directory stores:

  • server settings, projects and build configurations with their settings (i.e. all that is configured via the Administration web UI)

  • build logs and build artifacts

  • current operation files, internal data structure, etc.

For more details on the directory structure and data, refer to the TeamCity Data Directory section.

If necessary, you can exclude parts of the directory from the backup to save space — you will lose only the excluded data. You may safely exclude the "system/caches" directory from the backup — the necessary data will be rebuilt from scratch on TeamCity startup. If you decide to skip the backup of data under < >/system directory, make sure you note the most recent files in each of the artifacts, messages and changes subdirectories and save this information. It will be needed if you decide to restore the database backup with the TeamCity Data Directory corresponding to a newer state than the database. The < >/system/buildserver.* files store internal database (HSQLDB) data. You should back them up if you use HSQLDB (the default setting).

database_dataDatabase Data

Database stores all information on the build results (build history and all the build-associated data except for artifacts and build logs), VCS changes, agents, build queue, user accounts and user permissions, etc.

  • If you use HSQLDB, internal database (default setting, not recommended for production), the database is stored in the files residing directly in the < >/system folder. All files from the directory can be backed up. You may also refer to the HSQLDB backup notes.

  • If you use external database, back up your database schema used by TeamCity using database-specific tools. For the external database connection settings used by TeamCity, refer to the < >/config/ file. You can also see the Setting up an External Database.

Application Files

You do not need to back up TeamCity application directory (web server alone with the web application), provided you still have the original distribution package and you didn't:

  • place any custom libraries for TeamCity to use

  • install any non-default TeamCity plugins directly into web application files

  • make any startup script/configuration changes.

If you feel you need to back up the application files:

  • If you use a non-war distribution: back up everything under <TeamCity Specific Directories> except for the temp and work directories.

  • If you use the war distribution, pursue the backup procedure of the servlet container used.

Log files

If you need TeamCity log files (which are mainly used for problem solving or debug purposes), back up the <TeamCity home directory>/logs directory.

Manual Restoration of Server Backup

If you need to restore backup created with the web UI or maintainDB utility, please refer to Restoring TeamCity Data from Backup. This section describes restoration of a manually created backup.

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

TeamCity Data Directory Restoration

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, make sure the files created after the backup was done are cleared. Especially the newly created files under the artifacts, messages, changes directories under < >/system.

TeamCity Database Restoration

When restoring database, ensure there are no extra tables in the schema used by TeamCity.

Restoration to New Server

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

Last modified: 20 April 2023