Upgrade

In this section

Upgrading the TeamCity Server:

• win

• dist

Upgrading Build Agents:

• Automatic-Build-Agent-Upgrading

• upgradingAgent

  • Upgrading-Build-Agent-Launcher

  • Upgrading-the-Build-Agent-Windows-Service-Wrapper

Licensing Issues

Upgrades to TeamCity versions up to versions 4.x are free of charge. Please note that TeamCity 4.x uses new licensing policy comparing to that of previous TeamCity versions. Please review the new Licensing Policy.

Upgrading Using a Windows Installer

1. Shut the server down.

2. Shut the agent down if it was installed from the TeamCity installation package.

3. Locate the .BuildServer folder on the disk and TeamCity Data Backup of this folder (usually this folder is created in the home directory of the user under which the TeamCity server is running).

4. Back up the configuration files in the TeamCity installation folder if you modified them or installed custom plugins.

5. Uninstall the previous installation using Add or Remove Programs.

6. Run the new installer. When prompted, specify the <TeamCity data directory> used by previous installation.

7. If you use an external database put the appropriate driver jar into the <TeamCity home dorectory>/ROOT/WEB-INF/lib directory.

8. If you use custom plugins, put their jars into <TeamCity installation folder>/ROOT/WEB-INF/lib for server-side plugins and into <home directory>/ROOT/update/plugins for build agent plugins.

9. Start up the TeamCity server (and agent if it was installed together with the installer).

10. If your project contains build configurations related to *.ipr and inspections, you are required to update and correct the build configuration settings. To do it, visit the build configuration page/build runner section. The first visit to this page may take time, because TeamCity will download and analyze all the project module (*.iml) files to detect which global libraries, path variables, jdk, etc. are used. Subsequent visits will be much faster. Review the settings and make sure that all the settings are correct.

Manual Upgrading on Linux and for WAR Distributions

1. Shut the server down.

2. Locate the <TeamCity data directory> on the disk and TeamCity Data Backup of this folder (usually this folder is created in the home directory of the user under which the TeamCity server is running).

3. Back up old TeamCity files (either the whole TeamCity directory or [TOMCAT_HOME]/webapps/TeamCity/* if you are installing from a war file).

4. Remove old installation files (either the whole TeamCity directory or [TOMCAT_HOME]/webapps/TeamCity/* if you are installing from a war file).

5. Unpack the new archive where TeamCity was previously installed.

6. If you use an external database put the appropriate driver jar into the WEB-INF/lib directory.

7. If you use custom plugins, put their jars into ROOT/WEB-INF/lib for server-side plugins and into ROOT/update/plugins for build agent plugins.

8. Specify additional TeamCity Startup Properties, if required.

9. Start up the TeamCity server.

10. If your project contains build configurations related to *.ipr and inspections, it is required to update and correct build configuration settings. To do it, visit the build configuration page/build runner section. The first visit to this page may take time, because TeamCity will download and analyze all project module (*.iml) files to detect used global libraries, path variables, jdk and so on. Subsequent visits will be much faster. Look through the settings and make sure that all settings are correct.

All the configuration data and database scheme will by updated by our converters upon the first startup after the upgrade.

Automatic Build Agent Upgrading

In TeamCity 4.0 (like in TeamCity 3.0), the core components and plugins for build agents are updated automatically. When the TeamCity server is upgraded, agents will automatically update themselves. The agent (agent.bat, agent.sh, or agent service) will download the latest agent upgrade 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 agent is restarted). This process may take about five minutes. It is important not to interrupt the upgrade process, doing so may cause the upgrade to fail and the agent will need to be manually reinstalled.

Upgrading Build Agents to 4.0

When upgrading to TeamCity 4.0 for the first time there are two parts of the agent that need to be upgraded manually: the Windows service wrapper and the agent launcher. The easiest way to upgrade an agent is uninstall current build agent and then install the newer one.

Upgrading Build Agent Launcher

You only need to perform this step if you do not want to uninstall and then install the agent again, which is the preferred way of agent upgrade.

Agent launcher is the process that is first started for the agent and manages other child processes that actually connect to the server and perform the build.

1. Wait till agent is upgraded automatically.

2. Check <agent>\lib\latest folder. If it does not exist, no further steps are needed, you have the latest launcher version installed.

3. Stop agent.

4. Move content of the <agent>\lib\latest folder to the <agent>\lib folder, overwriting existing files, if needed.

5. Start the agent.

Upgrading the Build Agent Windows Service Wrapper

Upgrading from TeamCity version 1.x

Version 2.0 of TeamCity migrated to new way of managing Windows service (service wrapper) for the build agent: Java Service Wrapper library.

One of advantages of using new service wrapper is ability to change any JVM parameters of the build agent process.

1.x versions installed Windows service under name agentd, while 2.x versions use TeamCity Build Agent Service <build number> name.

The service wrapper will not be migrated to new version automatically. You do not need to use the new service wrapper, unless you need its functionality (like changing agent JVM parameters).

To use new service wrapper you should uninstall old version of the agent (with Control Panel | Add/Remove Programs) and then install a new one.

If you customized the user under which the service is started, do not forget to customize it in the newly installed service.

Upgrading from TeamCity version 2.x

If the service wrapper needs an update, the new version is downloaded into the <agent>/launcher.latest folder, however the changes are not applied automatically.

To upgrade the service wrapper manually, do the following:

1. Ensure the <agent>/launcher.latest folder exists.

2. Stop the service using <agent>\bin\service.stop.bat.

3. Uninstall the service using service.uninstall.bat.

4. Backup <agent>/launcher/conf/wrapper.conf file.

5. Delete <agent>/launcher.

6. Rename <agent>/launcher.latest to <agent>/launcher.

7. Edit <agent>/launcher/conf/wrapper.conf file. Check that the 'wrapper.java.command' property points to the java.exe file. Leave it blank to use registry to lookup for java. Leave 'java.exe' to lookup java.exe in PATH. For a standalone agent the service value should be ../jre/bin/java, for and agent installation on the server the value should be ../../jre/bin/java. The backup version of wrapper.conf file may be used.

8. Install the service using <agent>\bin\service.install.bat.

9. Make sure the service is running under the proper user account. Please note that using SYSTEM can result in failing builds which use MSBuild/Sln2005 configurations.

10. Start the service using <agent>\bin\service.start.bat.