TeamCity 2018.x Documentation

[Documentation for Previous Versions]

Icon

You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the [listing] to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Old Version 1

changes.mady.by.user Julia Alexandrova

Saved on

compared with

New Version Current

changes.mady.by.user Maria Kudryavtseva

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

TeamCity supports upgrades from any of the previous versions to the later ones. All the settings and data are preserved unless noted in the Upgrade Notes.

It is recommended to plan for regular upgrades to run the latest TeamCity version at least after several bugfix updates are released. This way you run a fully supported version with the latest fixes and security patches.

On this page:

Table of Contents

...

  1. For a major upgrade, review what you will be getting in What's New (follow the links at the bottom of What's New if you are upgrading not from the previous major release)
  2. Check your license keys unless you are upgrading within bugfix releases of the same major X.X version
  3. Download the new TeamCity version (extended download options)
  4. Carefully review the Upgrade Notes
  5. Consider probing the upgrade on a test server
  6. If you have non-bundled plugins installed, check plugin pages for compatibility with the new version and upgrade/uninstall the plugins if necessary

...

  1. Back up the current TeamCity data
  2. Perform the upgrade steps:

If you plan to upgrade a production TeamCity installation, it is recommended to install a test server and check its functioning in your environment before upgrading the main one.

...

Before upgrading, please make sure the maintenance period of your licenses is not yet elapsed (use Administration | Licenses TeamCity server web UI page to list your license keys). The licenses are valid only for the versions of TeamCity with the effective release date within the maintenance period. See the effective Check the effective release date on this pagethe releases list.
Typically all the bugfix updates (indicated by changes in the Z part of the X.Y.Z TeamCity version) use the same effective release date (that of the major/minor release).
If not all the licenses cover the target version release date, consider renewing the licenses before the upgrade (you can replace the old license keys with the renewed ones even before the upgrade).

...

Agents connected to the server are upgraded automatically.

Info

Important note on TeamCity data structure upgrade
TeamCity server stores its data in the database and in TeamCity Data Directory on the file system. Different TeamCity versions use different data structure of the database and data directory. Upon starting newer version of TeamCity, the data is kept in the old format until you confirm the upgrade and data conversion on the Maintenance page in the web UI. Until you do so, you can back up the old data; however, once the upgrade is complete, the data is updated to a newer format.
Once the data is converted, downgrade to the previous TeamCity versions which uses different data format is not possible!
There are several important issues with data format upgrade:

  • Data structure downgrade is not possible. Once newer TeamCity version changes the data format of database and data directory, you cannot use this data to run an older TeamCity version. Please ensure you backup the data before upgrading TeamCity.
  • Both the database and the data directory should be upgraded simultaneously. Ensure that during the first start of the newer server it uses the correct TeamCity Data Directory that in its turn has the correct database configured in the <TeamCity Data Directory>\config\database.properties file. Also make sure the data directory is complete (e.g. all the build logs, artifacts, etc. are in place), no data directory content supports copying from the data directory of the older server versions.

If you accidentally performed an inconsistent upgrade, check the recovery instructions.

hidden-data
Used in UI

Automatic Update

Since TeamCity 2017.2 automatic update option is available. For that to function, TeamCity server should be able to contact https://www.jetbrains.com site.
When a new version of TeamCity is detected, the server displays the corresponding health item for system administrators.
Since TeamCity 2017.2, the health The item points to the server's Administration | Updates page, where all the versions available for the update are listed. The page contains notes about licenses compatibility, the new version description and controls to perform the automatic upgrade if you want to use that instead of performing the manual updating procedure.

...

  1. The TeamCity server is stopped.
  2. The update script is run to do the following:
    1. Create a backup of the current installation in the TeamCity home/.old directory.
    2. Update the stopped server to the new version.
  3. Next, the updated server starts.
    The update progress is logged to the TeamCity home/logs/teamcity-update.log file.

 

Note

In case of an automatic update failure, perform the following to restore your TeamCity to the state prior to the update:

  1. Stop your TeamCity server if it is running
  2. In your TeamCity home directory, remove the folders with the same name as the ones in the <TeamCity server home>/.old directory
  3. Copy the contents of the <TeamCity server home>/.old directory to the <TeamCity server home> directory
  4. Start the TeamCity server

Current automatic update limitations:

  • some customizations, e.g. installations with changed server context, are not supported by automatic update
  • only manual upgrade is possible if the server is deployed from a .war distribution, or runs under the official TeamCity Docker container, started with AWS CloudFormation template or  Azure Azure Resource Manager template.
  • the Windows uninstaller is not updated during the upgrade, so after several updates, old TeamCity version will still be noted in Windows lists. During the uninstallation, not all of the TeamCity installation files might be deleted.
  • the bundled Java is not updated
  • with several nodes installation, only the main TeamCity server can be auto-updated, the Running Builds node needs to be updated manually.

Manual Upgrade

This section is applicable to TeamCity prior to 2017.2, as well as to the servers running under the official TeamCity docker container, started with AWS CloudFormation template or Azure Resource Manager template.

Anchor
win
win
Upgrading Using Windows Installer

  1. Create a backup. When upgrading from TeamCity 6.0+ you will also have a chance to create a backup with the "basic" profile on the TeamCity Maintenance Mode page on the updated TeamCity start.
  2. Note the username used to run the TeamCity server. You will need it during the new version installation.
  3. If you have any of the Windows service settings customized, store them to repeat the customizations later.
  4. Note if you are using 64 bit Java to run the service (e.g. check for "64" in "Java VM info" on the server's Administration | Diagnostics or in a thread dump), consider backing up <TeamCity home>\jre directory.
  5. (optional as these will not be overwritten by the upgrade) If you have any customizations of the bundled Tomcat server (like port, https protocol, etc.), JRE, etc. Backup those to repeat the customizations later.
  6. Note if you have local agent installed (though, it is not recommended to have a local agent) so that you can select the same option in the installer.

  7. Run the new installer and point it to the same place TeamCity is installed into ( the location used for installation is remembered automatically). Confirm uninstalling the previous installation. The TeamCity uninstaller ensures proper uninstallation, but you might want to make sure the TeamCity server installation directory does not contain any non-customized files after uninstallation finishes. If there are any, backup/remove them before proceeding with the installation.

    Info

    The main server configuration file <TeamCity Home Directory>/conf/server.xml is updated automatically when there were no changes to it since the last installation. If modification were made, the installer will detect them and backup the old server.xml file displaying a warning about the overwrite and the backup file location. Other files under conf can be overwitten to their default content as well, so if you have made manual modifications in those, check them after the upgrade.

  8. When If prompted, specify the <TeamCity data directory> used by the previous installation.
  9. (Optional as these will not be overwritten by the upgrade) Make sure you have the external database driver installed (this applies only if you use an external database).
  10. Check and restore any customizations of Windows services and Tomcat configuration that you need. When upgrading from versions 7.1 and earlier, make sure to transfer the server memory setting to the environment variables.
  11. If you were using 64 bit Java to run the server restore the <TeamCity home>\jre directory previously backed up or repeat the 64 bit Java installation steps.
  12. If you use a customized Log4j configuration in the conf\teamcity-server-log4j.xml file and want to preserve it (note, however, that customizing the file is actually not recommended, use logging presets instead), compare and merge conf\teamcity-server-log4j.xml.backup created by the installer from the existing copy with the default file saved with the default name.  Since TeamCity 2017.1 compare Compare the conf\teamcity-*-log4j.xml.dist file with the corresponding conf\teamcity-*-log4j.xml file and make sure that .xml file contains all the .dist file defaults. It is recommended to copy the .dist file over to the corresponding .xml file until you really need the changed logging configuration.
  13. Start up the TeamCity server (and agent, if it was installed together with the installer).
  14. Review the TeamCity Maintenance Mode page to make sure there are no problems encountered, and confirm the upgrade by clicking the corresponding button. Only after that all data will be converted to the newer format.

...

It is recommended for all users to regularly update their IDE plugins to the latest version compatible with the TeamCity server version in use. At least to the version available from the TeamCity server's Tools section on user profile.
Generally, versions of the IntelliJ IDEA TeamCity plugin, Eclipse TeamCity plugin, and Visual Studio TeamCity Addin have to be the same as the TeamCity server version. Users with non-matching plugin versions get a message on an attempt to log in to the TeamCity server with a non-matching version.
The only exception is TeamCity versions 9.0 - 9.1.x, which use a compatible protocol, and any plugin of these versions can be used with any server of these versions. Updating IDE plugins to the matching server version is still recommended.

Upgrading Build Agents

Anchor
AutoAgentUpgrading
AutoAgentUpgrading

...

On starting TeamCity server (and updating agent distribution or plugins on the server), TeamCity agents connected to the server and correctly installed are automatically updated to the version corresponding to the server. This occurs for both server upgrades and downgrades. If there is a running build on the agent, the build finishes. No new builds are started on the agent unless the agent is up to date with the server. 

Since TeamCity 2018.2, before starting the agent upgrade, the agent is checked for free disk space, 3 gb by default. To modify the value required for the upgrade, configure the teamcity.agent.upgrade.ensure.free.space agent property.

The agent update procedure is as follows: The agent (agent.bat, agent.sh, or agent service) will download the current agent package from the TeamCity server. When the download is complete and the agent is idle, it will start the upgrade process (the agent is stopped, the agent files are updated, and the agent is restarted). This process may take several minutes depending on the agent hardware and network bandwidth. Do not interrupt the upgrade process, as doing so may cause the upgrade to fail and you will need to manually reinstall the agent.

...

In the latter case, if you run the agent under Windows using a service, you may also need to upgrade the Windows service as described below.

Anchor
upgradingBuildAgentsServiceWrapper
upgradingBuildAgentsServiceWrapper

...