Creating and Managing tc Runtime Instances

After you install VMWare Tanzu tc Server components on all relevant computers, you can perform some or all of the following post-installation tasks, depending on the edition of tc Server.

Best Practices for Creating tc Runtime Instances

Please review the Best Practices: Creating tc Runtime Instances Guide for tips on best practices for creating tc Runtime Instances

Create and Modify a tc Runtime Instance Manually

The following sections describe how to create new instances of tc Runtime and provide related information.

The procedural topics cover both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platform, change these to back slashes (\).

Setting default values

It is possible to set default values for various command line options. Please see the included conf/tcserver.default.properties file for more details.

Using the tc Runtime Templates

A template is simply a directory that contains additional or customized tc Runtime instance files. For example, the directory might contain a conf/server-fragment.xml file, which the tc-server-10.1 script uses to update the base server.xml file with the relevant feature. The directory might also contain additional JAR files.

Templates make it easier to automatically configure certain tc Runtime features when you create a new tc Runtime instance or after you have already created it. These features include SSL, clustering, and so on.

Creating a Runtime Instance with the tc Runtime Templates

When you create a new tc Runtime instance, you use the --template option to specify a template to the tc-server-10.1 create command, or to the tc-server-10.1 apply-template command if you want to apply a template to an existing tc Runtime instance. When creating a new instance, you can specify the --template option multiple times if you want to apply multiple templates, such as clustering and SSL. When applying a template to an existing instance, you can specify the --template only once per script execution.

To use this feature, the specified template must already exist. You can use one of the out-of-the-box templates or one that you create yourself.

The argument to the --template option of the tc-server-10.1 script must exist in the tc Server template directory. The tc-server-10.1 command looks for the template directory in the templates directory included as part of the Tanzu tc Server distribution or the custom directory specified by the templates.directory configuration property.

The following example shows how to create a new tc Runtime instance called demo-instance using the nio out-of-the-box template which adds a NIO Connector to the server.xml file:

tc-server-10.1 create --template nio demo-instance

In the preceding example, because it does not specify the --java-home option, the instance uses the value of JAVA_HOME from the environment.

The following example shows how to create an instance that uses two templates:

tc-server-10.1 create demo-instance --template nio-ssl --template jmx-ssl

The above uses the create subcommand of tc-server-10.1 as example. It is recommended to use instance descriptor files when creating instances and specifying the template in that file.

What the tc-server-10.1 Command Does to Create a Runtime Instance

When you create a tc Runtime instance using tc-server-10.1, the script performs the following high-level steps:

Creates the instance directory and applies the base template to it. This template provides configuration common to all tc Runtime instances, such as ensuring that the instance can be monitored with by a JMX client.
If you specified one or more templates with the --template option, the command applies each template in order. First the script copies over any non-configuration files (such as JAR files) to the appropriate instance directory, and then the script merges the configuration file fragments with the instance configuration files. You receive a warning if the creation of the instance copies over files with the same name and directory location from two or more different templates.
Applies any needed configuration properties. The script gets the value of these properties either interactively from you, from the --property or --properties-file options you might have specified at the command-line, or from the default property values if no value is provided.
If there are no <Connector> elements in the server.xml file after the templates have been applied, the tc-server-10.1 command adds a Non-blocking IO (NIO) HTTP Connector to the instance.
Creates a README.txt file in the instance directory that lists the templates that have been applied to the instance.

When you apply a template to an existing instance, the script applies the configuration properties and updates the README.txt appropriately.

Template Directory Structure

The files that make up a template reside in a single directory; the name of the template directory is the name of the template. The template files are organized in the standard Tomcat subdirectory hierarchy. For example, configuration files live in the conf subdirectory and JAR files live in the lib subdirectory. The configuration files in the conf template directory are actually just fragments of XML, called server-fragment.xml or context-fragment.xml, that contain just the additions, deletions, or changes that the command applies to the base instance. When the tc-server-10.1 command applies the template after it has created a new base tc Runtime instance, it merges the XML fragment files with the corresponding base conf/server.xml or conf/context.xml file, and copies over any other files, such as JAR files. Depending on the contents of the template directory, the new tc Runtime instance might be quite different from the standard one. For example, the template might modify the standard server.xml file with additional server configuration, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

Templates Provided by tc Server

tc Server provides several out-of-the-box templates. Most are server configuration related; for example, one template sets up a basic cluster node configuration and another sets up SSL. Some templates are provided only in certain editions of tc Server, such as the manager template in the Developer Edition.

The following example shows how to use the nio out-of-the-box template to create a tc Runtime instance that is automatically configured with the NIO Connector in its server.xml file:

tc-server-10.1 create demo-instance-nio --template nio

Because the nio template is in the templates directory, you simply specify its name at the --template option.

The following table lists the templates that are provided by tc Runtime out-of-the-box and how each template differs from the generic tc Runtime instance (created without a specific template.) The Tanzu tc Server distribution includes these templates.

Template Name	Comparison with Default tc Runtime Instance
base	Base from which all new tc Runtime instances are created. It provides the configuration that is common to all tc Runtime instances, such as ensuring that the instance can be monitored by a JMX client.
ajp	Adds an Apache JServer Protocol (AJP) connector, which enables Apache web server to communicate with the tc Runtime instance. For details about the connector, see The AJP Connector in the Apache Tomcat Configuration Reference.
apr	Adds a `APRLifecycleListener` to detect the APR-based native library required to use the APR/native connector. Adds the APR HTTPS connector. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Apache Portable Runtime (APR) based Native library for Tomcat on the Apache Tomcat Web site.
apr-ssl	Adds an `APRLifecycleListener` to detect the APR-based native library required to use the APR/native connector. Adds an APR HTTPS connector. Generates a self-signed certificate and public key file, located by default in the `conf` directory. Disables SSLv2 support. The available ciphers are limited to those allowed by VMware. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Additional Information About Using the SSL Templates. For general information about APR and SSL, see Apache Portable Runtime (APR) based Native library for Tomcat and SSL Configuration HOW-TO on the Apache Tomcat Web site.
cluster-node	Adds the default Cluster configuration at the Engine level. By default, multicast discovery is used to identify other nodes in the cluster. If multicast is not enabled on the subnet or if multiple tc Runtime clusters may be present on the same subnet, reconfigure this cluster node to use static membership. Adds the `jvmRoute` attribute to the Engine element to uniquely identify the node. This is parameterized using `${tcserver.node}`, which is defined in the `CATALINA_BASE/conf/catalina.properties` file. tc Server provides a default value for the `jvmRoute` attribute. You can specify a value other than the default when you create the tc Runtime instance by specifying the `cluster-node.node.name` property using the `--property` option as follows: `--property cluster-node.node.name=my-node`. Because this template does not specifically add a Connector to the instance's `server.xml` file, the `tcserver` script will automatically add a Non-blocking IO (NIO) HTTP connector. For more information, see Clustering/Session Replication HOW-TO on the Apache Tomcat Web site.
diagnostics	Adds a sample JDBC resource configuration that integrates with the request diagnostics to report slow queries. Adds a ThreadDiagnosticsValve at the Engine level to report on slow running requests.
nio	Adds a Non-Blocking IO (NIO) connector for HTTP. For more information, see The HTTP Connector on the Apache Tomcat Web site.
nio-ssl	Adds an NIO HTTPS connector. Generates a keystore that contains a self-signed certificate and a public key, and stores it in the `conf` directory by default. Disables SSLv2 support. The available ciphers are limited to those allowed by VMware. For more information, see Additional Information About Using the SSL Templates). For general information, see The HTTP Connector and SSL Configuration HOW-TO) on the Apache Tomcat Web site.

Additional Information About Using the SSL Templates

If you specify one of the SSL templates (nio-ssl, apr-ssl, or jmx-jaas-ssl) when you create a tc Runtime instance, the tc-server-10.1 command automatically configures SSL or OpenSSL for the instance; generates a new keystore; and provides default values for various properties if you do not specify them interactively.

For example, assume that you used the following command to create an instance:

tc-server-10.1 create demo-instance-secure -t nio-ssl

The demo-instance-secure instance has the following default SSL properties and configuration:

A generated keystore, located in the conf directory, with the name tc-server-nio-ssl.keystore. This keystore contains a self-signed certificate with default values (such as Unknown) for the organization information.
Key alias named tc-server-nio-ssl.
Key password consisting of a random string of characters.
Keystore password that is the same as the key password
HTTPS port of 8443.

This default configuration is adequate for testing. Typically, when you move to a production environment, you want to generate keystores with real information about your organization and customize the passwords. In this case, use the --interactive option of tc-server-10.1 so that the script prompts you for the information about your particular environment.

The --interactive option still generates a self-signed certificate. If you require an authentic, verified certificate, purchase one from a well-known Certificate Authority such as VeriSign, and use the keytool JDK tool to import the certificate into your keystore. See the Creating a Simple Keystore File For Both SSL and OpenSSL section in the VMWare Tanzu tc Server Administration Guide in this Documentation Center for more information.

Starting and Stopping tc Runtime Instances Manually

The following sections describe how to start and stop tc Runtime instances on both Unix and Windows platforms.

On Unix platforms, you typically use shell scripts to start and stop tc Runtime instances; alternatively, you can configure your Unix boot process to start the instance automatically. On Windows, you first install the tc Runtime instance as a Windows Service. You can use the tc-server-10.1 script or the Windows Services console to start and stop it.

Linux: Systemd based startup script
Windows: Starting and Stopping tc Runtime Instances as Windows Services
The Windows Java Service Wrapper
Windows: Setting the Logon-as-Service Right for a Windows User

Linux: Systemd based startup script

For systemd based linux systems a template is provided which generates an instance specific server file located at conf/tcruntime.service. This file is an example of the .service script. It should be reviewed after being created.

In order to create the file the systemd template needs to be applied to an instance. This is an option with either create time or apply-template.

tc-server-10.1 apply-template instancename -t systemd

By default the tcruntime.service file will be configured to use a user tc-server-10.1 to run the instance as. This user needs permissions to the instance directory and the tc Server installation directory.

The user may be changed by specifying a value for the property systemd.runtime.user when using the template.

tc-server-10.1 create instancename -t systemd -p systemd.runtime.user=instance

After the file has been created and reviewed it should be copied, not symlinked, to /etc/systemd/system. Then the standard commands may be used to enable and control the service.

sudo systemctl enable tcruntime
sudo systemctl start tcruntime

Windows - Starting and Stopping tc Runtime Instances as Windows Services

By default, the tc-server-10.1 script creates all tc Runtime instances under the instances directory, which is configured in the tc Server configuration properties or defaults to a location relative to the tc-server-10.1 command. Each particular tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance. If so, adjust the following procedure accordingly.

To start and stop tc Runtime instances as Windows Services:

Login to the computer on which you installed tc Server as the user who will run the tc Runtime instance, such as tcserver.
If this is the first time that you will install and start the tc Runtime instance after creating it, start a Command Prompt window and continue with this procedure.

If you have already installed the tc Runtime instance as a Windows Service, use the Windows Services control panel to start and stop it.
Install the tc Runtime instance as a Windows service:
```
tc-server-10.1 install demo-instance
```
The command installs the tc Runtime instance as an automatic Windows Service, which means that the tc Runtime instance starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel.
Start and stop the tc Runtime instance using the tc-server-10.1 script or the Windows Services console. The tc Runtime instance is displayed in the console with the name VMware tc Runtime instance - unique-name, where unique-name is a unique combination of server name and server directory.

To start an instance using tc-server-10.1:
```
tc-server-10.1 start demo-instance
```
To stop an instance using tc-server-10.1:
```
tc-server-10.1 stop demo-instance
```

To uninstall the tc Runtime service on Windows, execute the following command:

tc-server-10.1 uninstall demo-instance

Although VMware recommends that you always install the tc Runtime instance as a Windows service and stop and start it using the Services console, you can also stop and start the tc Runtime instance manually.

Windows - Setting the Logon-as-Service Right for a Windows User

The install command has the optional --username parameter by which you specify the user account that you want the tc Runtime service to run as when you start the service from the Windows Service console. Windows requires that the specified user account must have their Logon as Service right set for this feature to work properly. To set this right:

From the Windows Start menu, open the Control Panel.
Open Administrative Tools.
Open the Local Security Policy tool.
Expand the Local Policies settings.
Click the User Rights Assignment.
On the right side, double-click on the Log on as a service policy.
Click on the Add User Or Group button and enter the user account name using the wizard.

The Local Security Policy tool does not appear to be available on Home versions of Windows 2000 and XP. It is thus not possible to run the tc Runtime service as a specific account under those versions of Windows.

Deploy Applications to tc Runtime Instances

Deploying Applications Using Tomcat Manager

The tc Server Standard Edition includes a template used to install and configure Tomcat Manager and tc Server Developer Edition includes the Tomcat Manager web application. Tomcat Manager is an Apache Web application that you can use to deploy your own Web applications and manage their lifecycle, such as starting, stopping, and undeploying them.

The default tc Server Developer Edition configuration does not automatically authorize any user to access Tomcat Manager, so you must configure a role and a user before you can use Tomcat Manager. The Tomcat Manager web application is updated in Tomcat 7.0 with separate roles to secure access to the application from different paths. To use a Web browser to deploy Web applications, you need the manager-gui role for tc Runtime 7. Refer to the Apache Web site for complete documentation for Tomcat Manager.

The following procedure describes how to authorize a user to access Tomcat Manager, and then how to invoke the Web application in your browser.

Procedure

Update the CATALINA_BASE/conf/tomcat-users.xml file in the tc Runtime instance by adding a manager-gui role.

An entry for the manager-gui role for tc Runtime 7 or tc Runtime 8 looks like this:
```
<tomcat-users>
  <role rolename="manager-gui" />
  ...
</tomcat-users>
```
In the same file, add a user with the manager or manager-gui role, depending on your tc Runtime version.

The user element looks like the following:
```
<tomcat-users>
  <role rolename="manager-gui" />
  <user username="tomcat" password="tomcat" roles="manager-gui" />
</tomcat-users>
```
Restart the tc Runtime instance for the changes to take effect.
Invoke Tomcat Manager in your browser using the following URL:
```
http://host:8080/manager/html
```
where host refers to the computer running the tc Runtime instance.
Enter the user and password you configured in the tomcat-users.xml file.

The Applications table lists the currently deployed applications. Click the links in the Path column to actually invoke each application. The Commands column includes buttons for starting, stopping, reloading, and undeploying the applications.

From the Deploy section, you can deploy Web applications (either exploded or in a WAR format) from either the host where running the tc Runtime instance or from the local computer running your browser. When deploying from the host, you must specify the context path that users use to invoke the application.

For detailed information about Tomcat Manager, see the Manager App How-To on the Apache Tomcat Web site.

Deploying Multiple Versions of the Same Application

You can deploy multiple instances of the same web application to a tc Server instance. New sessions are served by the most recently deployed revision of the application. This allows you to upgrade an application without interruption of service.

If you deploy an application statically or with Tomcat Manager, you must include a revision indicator string in the .war file name prefix in the /webapps directory. The revision indicator distinguishes amont multiple instances.

You must conform to the following naming convention. Starting with the second instance, indicate the version as a 6 character numeric value, prepended by two hash marks, increasing the value for each revision. For instance:

test##000001.war
test##000002.war
test##000003.war

Users continue to use the same URL to access the application. They do not include the revision number. New sessions use the highest revision deployed. Existing sessions continue to use the revision that is already managing their session. If tc Runtime cannot locate the session in the SessionManager of an earlier revision, the newest revision is used.

When all sessions using an earlier revision of an application have ended, you can undeploy it.