Best Practices: Upgrading tc Server and components

This document describes the best practices for upgrading tc Server from older versions (e.g. 4.1.x to newer versions (e.g. 10.1.x)..

Please note: If following Best Practices for creating and managing instances the recommended means of upgrading an instance is to recreate it using an instance descriptor file with the newer version of tc Runtime version in the file instead of manually upgrading the configuration.

Distinction between tc Server, tc Runtime, and tc Runtime Instances

Before beginning, it is important to note the difference between tc Server components and how they work together.

tc Server is the product name. This refers to the entire distribution of tc Server which includes the tc Runtime and templates.

tc Runtimes are Tanzu packaging of the Apache Tomcat binaries. These packages are functionally equivalent to the ones created by the Apache Software Foundation. They are the runtimes that are configured and used to by your tc Runtime instance’s configuration.

tc Runtime Instance is a configured servlet container that will host your web application, data, configuration, logs, and anything else that is part of the Tomcat CATALINA_HOME. These instances are configured to use a tc Runtime version and managed by the tc Server scripts.

Best Practices for Upgrades

  1. Use default directory layouts - By default tc Server uses separate directories for tc Server, tc Runtimes, and tc Runtime Instances.
  2. Use templates for all configuration changes - Instead of editing conf/server.xml or other configuration files directly, create a template which contains the desired changes.
  3. Use instance descriptor files to create tc Runtime Instances - This provides a simple way to configure and track how an instance was created and allows for it to be recreated in the future if needed.
  4. Store templates and instance descriptor files in version control - This makes it easy to track changes and restore to a known good state.

Upgrading tc Server Version

The basic procedure for upgrading tc Server is as follows

  1. Create backups of tc Server, tc Runtimes, tc Runtime Instances, custom templates, and any additional tc Server related files.
  2. Download and install the latest tc Server (e.g. 5.0.x).

Upgrading from tc Server 4.1.x to 5.0.x release

In tc Server 3.x, the default location for an instance was in the current directory. This led to instances being created in random places or in the same directory as the tcruntime-instance script. This section describes how to relocate those instances into a single and separate tc Runtime Instances Directory

Note: At this time only upgrading in the same tc Runtime major version is supported. For example upgrading from 7.0.45.A to 7.0.109.B is supported however going from 7.0.109.B TO 9.0.46.B is not supported by this procedure. See below for more information on upgrading major versions of tc Runtime

Note: This procedure requires downtime of instances.

  1. Ensure you have the desired version of tc Runtime installed by checking for the latest tc Server version
  2. Stop the instance
  3. Ensure you have made a backup
  4. Run the following command tcserver upgrade /path/to/instance -v <version> where /path/to/instance refers to the instance directory of the previous version of tc Server and <version> refers to the desired tc Runtime version, which needs to be installed prior to running this command. This step will relocate the instance from the previous tc Server to the current one’s dedicated instance directory.
  5. Start the instance tcserver start <instanceName>.
  6. View logs and look for and address any issues tcserver logs <instanceName>

Due to the script renaming, you'll need to modify any startup scripts or other processes that look for the previous tcruntime-ctl scripts or the instance in the previous directory.

Upgrading from 5.0.x to the latest tc Server with a dedicated instances directory configured

A dedicated instances directory is used like a repository of instances. This is the default behavior of tc Server 4.0.0 and newer.

Check the conf/tcserver.properties file for a property value defined for instances.directory in the previous tc Server installation directory. if there is a value then the same value needs to be set in the new tc Server installation directory’s conf/tcserver.properties.

The default behavior is to use ../instances relative to the tcserver command location which should be the tc Server Installation directory unless a custom location is used..

The recommended directory structure is as follows

  • TCSERVER_HOME - Base directory of tc Server.
  • TCSERVER_HOME/standard-<version> - The directory containing specific tc Server versions which is expanded from the downloaded package from Tanzu Network. This contains the tcserver command and supporting files.
  • TCSERVER_HOME/instances - The dedicated tc Server Instances directory as mentioned above this is where instances should be created.
  • TCSERVER_HOME/runtimes - The dedicated directory to store tc Runtime versions.

If TCSERVER_HOME is /opt/tc-server/5.0.x/ then the following is an illustration of the subdirectories if multiple tc Server versions are installed.


In addition to checking for values set for instances.directory other properties set should be copied to the new tc Server installation's conf/tcserver.properties. The properties are not set by default except in the case of tc Server being installed via RPM or DEB packaging.

Upgrading tc Runtime Version

Upgrading instances using the same original configuration with a newer version of tc Runtime is the ideal approach, however, this is not always possible. The tc Server modify-version and upgrade commands do not support upgrading tc Runtime major versions. As a result, in order to upgrade, a new instance needs to be created with the newer tc Runtime version.

The instance will be created with the upgraded tc Runtime version along with the configuration and webapps copied to the new instance. The following guides may be used to migrate the configuration to the newer versions.

Note: The sections below should be considered a best effort approach.

Upgrading from tc Runtime version 7.0.x to 8.5.x

As noted above, our tc Runtimes are binary compatible with Apache Tomcat. So, we recommend following Apache Tomcat's migration guide and the following guides:

Upgrading from tc Runtime version 8.0.x to 8.5.x

As noted above, our tc Runtimes are binary compatible with Apache Tomcat. So, we recommend following Apache Tomcat's migration guide:

Upgrading from tc Runtime version 8.5.x to 9.0.x

As noted above, our tc Runtimes are binary compatible with Apache Tomcat. So, we recommend following Apache Tomcat's migration guide:

Upgrade from 7.0.x to 9.0.x

As noted above, our tc Runtimes are binary compatible with Apache Tomcat. So, we recommend following Apache Tomcat's migration guides:

Upgrade from 9.0.x to 10.1.x

As noted above, our tc Runtimes are binary compatible with Apache Tomcat. So, we recommend following Apache Tomcat's migration guides:

check-circle-line exclamation-circle-line close-line
Scroll to top icon