Upgrade and Migration Guide

Upgrade an Instance to a Newer tc Runtime Binary
Upgrade within Same Major Version (4.x -> 4.x)
Upgrade an Instance in a New tc Server Major Version (3.x to 4.x)

Please review the Upgrade Best Practices Guide which provides best practices on upgrading.

Upgrade an Instance to a Newer tc Runtime Binary

This section has instructions for upgrading tc Runtime instances to a new version of the tc Runtime.

For example, suppose that your tc Server release came bundled with 9.0.6.B.RELEASE. Later, you could decide to upgrade to the 9.0.46.B.RELEASE (or another version) when it is released. The instructions in this section enable you to stay current with new tc Runtime releases without fully installing the full tc Server installation. This lets you take advantage of getting the latest features, security vulnerability fixes, and bug fixes.

Before You Start

Be sure to stop a tc Server instance before you upgrade the tc runtime version. For instructions, see Starting and Stopping tc Runtime Instances.

Procedure

Change directory to the tc Server installation directory. For example:
```
cd /opt/pivotal/tcserver/standard-4.1.8.RELEASE
```

Use the list-runtimes command to view a list of available runtimes to install. The command connects to the tc Server tc Runtime repository server and may take a few seconds to return the list. For example:

Retrieving list of available tc Runtimes

    Available tc Runtimes:

        7.0.103.A.RELEASE
        7.0.103.B.RELEASE
        7.0.104.A.RELEASE
        7.0.104.B.RELEASE
        7.0.106.A.RELEASE
        7.0.107.A.RELEASE
        7.0.108.A.RELEASE
        7.0.109.A.RELEASE
        7.0.109.B.RELEASE
        8.5.53.A.RELEASE
        8.5.54.B.RELEASE
        8.5.56.A.RELEASE
        8.5.56.B.RELEASE
        8.5.58.B.RELEASE
        8.5.60.A.RELEASE
        8.5.63.A.RELEASE
        8.5.65.B.RELEASE
        8.5.66.B.RELEASE
        9.0.33.A.RELEASE
        9.0.34.B.RELEASE
        9.0.36.A.RELEASE
        9.0.36.B.RELEASE
        9.0.38.B.RELEASE
        9.0.40.A.RELEASE
        9.0.43.A.RELEASE
        9.0.45.B.RELEASE
        9.0.46.B.RELEASE

Runtimes are specified by version, such as 8.5.27.B.RELEASE. If ’- INSTALLED’ trails the version number, that indicates the runtime version is currently installed for this version of tcserver.

Use the get-runtime command to download and install a specific runtime version. For example:

$ tcserver get-runtime 9.0.46.B.RELEASE
Checking available tc Runtimes
Validating checksum of downloaded file: pass
Extracting tc Runtime version 9.0.46.B.RELEASE to /opt/pivotal/tcserver/runtimes
Installed tc Runtime version '9.0.46.B.RELEASE'

If the specified version is already installed, then the command returns a message similar to the following:

$ tcserver get-runtime 9.0.46.B.RELEASE
Checking available tc Runtimes
'get-runtime' command failed. Runtime version 9.0.46.B.RELEASE already exists

Upgrade within Same Major Version (4.x -> 4.x)

When installing the new version (e.g. 4.1.8.RELEASE) of tc Server it should be unpacked into the parent directory of the previous version (e.g. 4.0.3.RELEASE) of tc Server.

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/<edition>-<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. <edition> is either standard or developer and <version> is the version of tc Server. 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 /op/pivotal/tcserver 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.

Upgrade an Instance in a New tc Server Major Version (3.x to 4.x)

Note: tc Runtime instances can only be upgraded to the same major version number. For example: If current instance tc Runtime version is 7.0.84.B.RELEASE, you can not upgrade it to 8.5.x, or 9.0.x. You are required to create a new instance with the desired tc Runtime version and manually copy configuration over.

This section has instructions for upgrading tc Server instances to a new version of tc Server.

Run the tcserver upgrade command to upgrade an existing tc Server instance to a new version of tc Server. The upgrade command migrates configuration information and applications from an existing instance to the new one. The command takes this form:

 tcserver upgrade -v
        <tcRuntimeVersion> -i PathToNewInstanceDirectory PathToOldInstance

where:

tcRuntimeVersion is the Tomcat binary that you want the new instance to use, for example, 9.0.6.B.RELEASE.

Note:

The tc Runtime version must exist in the new tc Server installation directory. If you want to use a tc Runtime that exists in your previous tc Server installation, but not the new one, you must copy it into the new tc Server installation directory.
If you do not use the -v option to specify a binary version, the upgrade assumes you do not want to upgrade the binary and tries to create the new instance with the same binary. If the older instance uses a version of Tomcat that does not exist in the new version of tc Server, you must copy it from the older tc Server installation to the new one, or the upgrade will fail.

PathToNewInstanceDirectory specifies the directory in which you want the upgraded instance to be created.

Note:

If you do not use the -i option to specify a directory, the instance will be created in the tc Server instance directory.
If you specify the directory where the old instance exists, that instance will be upgraded in place.

PathToOldInstance points to the instance that you wish to upgrade.

Before You Start

Be sure to stop a tc Runtime instance before you upgrade. For instructions, see Starting and Stopping tc Runtime Instances.

Procedure

The example commands in the instructions below assume you are upgrading a tc Server 3.2.9 created instance to 4.0.0.RELEASE.

Install the new version of tc Server in a new installation directory, as described in Installing VMware tc Server. For example, install tc Server 4.0.0 in /opt/pivotal/tcserver/standard-4.0.0.RELEASE.
If the directory where you want the upgraded server instance to be installed does not exist, create it.
Change directory to new TCS installation directory. For example:
```
cd /opt/pivotal/tcserver/standard-4.1.8.RELEASE
```
Run the upgrade command. For example:
```
tcserver upgrade -i ../tcs-4.0.0-instances -v 9.0.6.B.RELEASE  ../tcs-3.2.9-instances/myserver1 
```
The command above creates an upgraded version of the “myserver1” instance in the ../tcs-4.0.0-instances directory.

Upgrading Java Version

It is recommended to create a duplicate instance prior to upgrading Java. The duplicate instance can be used for testing purposes.

To upgrade the java version, the JAVA_HOME variable in bin/setenv.sh (Unix) and the set.JAVA_HOME property in conf/wrapper.conf (Windows) needs to be updated to point to the new Java Home.

When upgrade from a Java version prior to 8 any PermGen settings should be removed. These are usually found in the JAVA_OPT variable in bin/setenv.sh

An example of a Java 6 setenv.sh

  # Edit this file to set custom options
  # Tomcat accepts two parameters JAVA_OPTS and CATALINA_OPTS
  # JAVA_OPTS are used during START/STOP/RUN
  # CATALINA_OPTS are used during START/RUN

  JAVA_HOME="/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home"
  AGENT_PATHS=""
  JAVA_AGENTS=""
  JAVA_LIBRARY_PATH=""
  JVM_OPTS="-Xmx512M -Xss256K -XX:MaxPermSize-512M"
  JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH"

An example of a Java 8 setenv.sh

  # Edit this file to set custom options
  # Tomcat accepts two parameters JAVA_OPTS and CATALINA_OPTS
  # JAVA_OPTS are used during START/STOP/RUN
  # CATALINA_OPTS are used during START/RUN

  JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk1.8.0_151.jdk/Contents/Home"
  AGENT_PATHS=""
  JAVA_AGENTS=""
  JAVA_LIBRARY_PATH=""
  JVM_OPTS="-Xmx512M -Xss256K"
  JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBRARY_PATH"

It may be necessary to set the -XX:MaxMetaspaceSize which by default is only limited by the amount of memory available to the java process. Not setting this value could result in a server crash. Do not set Metaspace to be the same as a previous PermGem size as they have different meanings and purposes.