Best Practice - Creating and Managing tc Runtime Instances

This guide is intended to provide best practices for creating and manage tc Runtime instances utilizing the full power of tc Server.

This guide using the Instance Descriptor Files feature of tc Server you will be walked through the process of creating reproducible tc Runtime Instances and creating a custom template for applying a connector to the tc Runtime Instance.

Assumptions:

• You have installed the latest version of tc Server 5.0.x
• You have access to a source control system such as git
• All commands are executed from the base directory of the tc Server installation

Getting Started

In this guide we will create a tc Runtime Instance with a custom nio connector and storing the configuration in a git repository.

Creating a template

For this example we are adding a second Connector to the server.xml file. This Connector will listen on port 8081 with a redirectPort of 8444. This is addition to the default Connector provided by the nio template which is added to all new tc Server Instances

        <Connector acceptCount="100"
                   connectionTimeout="20000"
                   disableUploadTimeout="true"
                   executor="tomcatThreadPool"
                   maxKeepAliveRequests="15"
                   port="8081"
                   protocol="org.apache.coyote.http11.Http11NioProtocol"
                   redirectPort="8444"/>

This fragment adds the disableUploadTimeout="true" attribute.

Let's create a tc Server template to apply our custom Connector configuration.

If it doesn't already exist create a directory to hold custom templates.

mkdir ../custom-templates

If creating the custom templates directory for the first time edit conf/tcserver.properties and add

templates.directory=../custom-templates

Next inside the custom-templates directory create the following layout

custom1/README.txt
custom1/conf/

The custom1/README.txt file should contain notes about what the template does. Can also include version information. The contents are appended to the tc Runtime Instance's README.txt file.

Inside the conf create a custom1/conf/server-fragment.xml file which contains the following text

<Server>
    <Service name="Catalina">
        <add:Connector acceptCount="100"
                   connectionTimeout="20000"
                   disableUploadTimeout="true"
                   executor="tomcatThreadPool"
                   maxKeepAliveRequests="15"
                   port="${http.port:8081}"
                   protocol="org.apache.coyote.http11.Http11NioProtocol"
                   redirectPort="${https.port:8444}"/>
    </Service>
</Server>

The above fragment has the minimum elements needed to identify to tc Server where the Connector gets added. The add: prefix to the Connector element is read by tc Server as meaning to add this element to the file. Note: The add: text itself will be not be added to the server.xml file

For change tracking the above contents of the custom directory should be added to revision control software such as git

Creating an Instance Descriptor File

An instance descriptor file contains the information which can be used to create a tc Runtime Instance. The options which would be specified to the create command are supplied in java properties form as input to the create-from-file command.

To use our custom template above the following contents should be added to a new file named example.properties.

name=example
template.1=nio
template.2=custom1

This is the most basic usage of a Instance Descriptor File. Since we are adding a second connector we must specify the nio and custom1 templates.

Again add this file to version control such as git.

Now let's create our instance

$ ./tcserver create-from-file example.properties

Creating instance 'example' at '/opt/tc-server/5.0.x/instances/example'
  Using tc Runtime version 10.1.17.B.RELEASE
  Setting JAVA_HOME for instance to '/opt/java/17.0.9-graalce'
  Using separate layout
  Creating bin/setenv.sh
  Applying template 'base'
  Applying template 'base-tomcat-101'
  Applying template 'nio'
  Applying template 'custom1'
  Configuring instance 'example' to use tc Runtime version 10.1.17.B.RELEASE
Instance created
Connector summary
  Port: 8080   Type: Non-Blocking IO   Secure: false
  Port: 8081   Type: Non-Blocking IO   Secure: false

The connector summary shows both connectors. This is how we know our custom template was successfully applied.

Best Practices Summary

• Always create production instances using Instance Descriptor Files.
• Always use templates for customizing instance configurations
• Always use property files or specify the properties in the Instance Descriptor Files instead of manually editing conf/catalina.properties file
• Store custom templates and Instance Descriptor Files in revision control system to track changes.

Using these best practices allow for recreating an instance quickly and easily. More importantly it makes upgrading instances between tc Runtime versions simpler as an instance can be recreated with the newer major version of tc Runtime.