7. Post-Installation Tasks

After you install the components of tc Server on all relevant computers, you perform some or all of the following post-installation tasks, depending on the edition of tc Server: Start and run the HQ Server and agents; create and start tc Runtime instances; deploy Web applications to an instance; or invoke and use the HQ user interface to monitor and configure tc Runtime instances. (As a performance-monitoring alternative to HQ, you can install and configure Spring Insight. See Using Spring Insight.)

Your first post-installation task depends on the layout of tc Server you want to use for your tc Runtime instances, whether SpringSource or Apache Software Foundation (ASF).

[Note]Note

It is assumed in most of this documentation that you are going to use the SpringSource layout for tc Runtime instances, rather than the ASF layout. The SpringSource layout offers many benefits over the standard ASF layout, although you can of course use the latter. For clarity, all ASF layout-specific documentation has been grouped into a single section; see Using the ASF Layout. Unless otherwise specified, the rest of the documentation assumes the SpringSource layout.

7.1 Creating a New tc Runtime Instance

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 (\).

Creating tc Runtime Instances: Typical Steps

This section describes the simplest way to create a new tc Runtime instance. For an explanation of the type of instance that the example creates, see the description following the procedure.

  1. Open a terminal window (Unix) or command prompt (Windows).

  2. Change to the INSTALL_DIR/springsource-tc-server-edition directory, where INSTALL_DIR refers to the main tc Server installation directory, such as /home/tcserver and edition refers to the edition of tc Server you are using (either node, developer, or standard.) For example:

    prompt$ cd /home/tcserver/springsource-tc-server-node
    [Note]Note

    This step is not required, because you can run the tcruntime-instance.sh|bat script from any location. The documentation provides this step for clarity about where the scripts live.

  3. Run the tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) script, passing it the required -s serverName parameter. Replace serverName with the name of your new tc Runtime instance. The -s option is the only required one. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.

    For example, on Unix:

    prompt$ ./tcruntime-instance.sh -s myserver 

    On Windows:

    prompt> tcruntime-instance.bat -s myserver 

When the preceding sample command completes, the new tc Runtime instance is located by default in the INSTALL_DIR/springsource-tc-server-edition/myserver directory (such as /home/tcserver/springsource-tc-server-node/myserver); you can specify a different instance directory with the -n instanceDir option. This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance.

By default, the tc Runtime instance uses the JDK or JRE pointed to by the JAVA_HOME or JRE_HOME environment variables, respectively, or the instance uses the java binary that it found in the PATH environment variable when it started. Because no JDK or JRE has been explicitly set, the tc Runtime instance is portable; see Creating Portable tc Runtime Instances for more information. You can specify a different location for the JDK or JRE with the -j or -r options.

The ports of the tc Runtime instance are the default values:

  • HTTP listen port: 8080

  • JMX port: 6969

  • AJP port: 8009

  • Shutdown port: -1

Because the preceding sample use of tcruntime-instance.sh|bat did not specify the -v version option, the version of the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script uses the highest version of the tc Runtime it can find in the installation directory, for example 6.0.25.A-RELEASE. See Pinning tc Runtime Instances to a Specific Version for more information.

When you use the tcruntime-instance.sh|bat command script to create an instance, you can specify additional optional parameters, as described in tcruntime-instance.sh Reference. For example, if tc Server is installed on a 64-bit Windows operating system and you are using a 64-bit JVM, then you can specify that the tc Runtime instance use a 64-bit service wrapper; by default, the Windows service wrapper is 32-bit. You can also use the -p parameter to specify different port numbers from the default ones, and the -n parameter to specify a directory in which the instance lives other than the default tc Runtime installation directory.

tcruntime-instance.sh Reference

The following table lists options of the tcruntime-instance.sh|bat command script.

You specify options with a single dash and a letter (such as -s) or with two dashes and a word (such as --server).

Table 7.1. Options of the tcruntime-instance Command Script

Option (Single Dash)Option (Double Dash)DescriptionRequired?
-c --create Creates a new tc Runtime instance.

This is the default mode of the script.

No.
-d tcRuntimeDir --tcruntimedir tcRuntimeDir Replaces tcRuntimeDir with the full pathname of the tc Server installation. Use this parameter if you are running the tcruntime-instance.sh script from a location other than its default home directory. The default value of this parameter is the tc Server installation directory, such as /home/tcserver/springsource-tc-server-node.Only required if you are not running the tcruntime-instance.sh from its default location: INSTALL_DIR/springsource-tc-server-edition, where edition refers to the Edition of tc Server you are using (either node, developer, or standard.)
-f --force Forces the script to create a new tc Runtime instance, even if one already exists. By default the script does not force the creation.

If you specify this parameter and a tc Runtime instance with the name already exists, the script replaces only the existing bin and conf directories; the script does not replace the other directories, such as lib or temp. It is assumed in this case that you want to replace only the Tomcat-specific files (typically because you're updating the Tomcat version), but do not want to touch the user-specific files, such as Web applications.

No.
-h --help Outputs information about all the available options of tcruntime-instance.sh|bat.No.
-i --interactive Tells the script to interactively ask for port numbers; use this parameter if you want to change the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps.

Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers.

No.
-j

-j path_to_jdk

--javahome

--javahome path_to_jdk

If specified without a path_to_jdk value, hard-codes the JAVA_HOME variable in various files of the instance, using the global JAVA_HOME environment variable value. You can also use this option to specify a different location of the JDK. In this case, replace path_to_jdk with the full pathname of the JDK.

If you do not specify this option at all, then the instance uses the JAVA_HOME global environment variable, and does not hard-code the value anywhere.

The tcruntime-instance.sh script includes options for setting the path to a JDK (i.e. JAVA_HOME) and the path to a JRE (i.e. JRE_HOME). Typically, JAVA_HOME points to any valid location of a JVM or JRE, whereas JRE_HOME points only to a JRE. For most use cases, setting the JAVA_HOME variable with this option is adequate, and you do not need to set JRE_HOME with the -r option.

Only required if you have not set the JAVA_HOME variable in your environment to point to the JDK.
-l --list Lists all tc Runtime instances known to this particular tc Server installation.

For each instance, the command outputs additional information, such as the parent directory of the instance, the directories that contain its command scripts and binaries, the version of the instance (both base Tomcat version and tc Server version), and whether the instance is currently running.

No.
-m --modifyver Modifies the version of tc Runtime that an existing tc Runtime instance uses when the instance is pinned to a particular tc Runtime version.

Use this option together with the -s serverName option to specify the tc Runtime instance you want to modify and with the -v version option to specify the new version of the instance. If you specify -m without specifying -v, the resulting instance is unpinned. See Pinning tc Runtime Instances to a Version.

Note: Use this option only with an existing tc Runtime instance; you cannot use this option when creating a new instance. Also, it is assumed that you have already installed the tc Runtime version to which you want to modify the existing instance.

No.
-n instanceDir --instancedir instanceDir Replace instanceDir with the full or relative pathname of the directory in which you want the new tc Runtime instance to be created. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntime-instance.sh|bat script.

The default value of this option is the tc Server installation directory, which means that if you do not specify this option, the tcruntime-instance.sh|bat script creates the new instances in the INSTALL_DIR/springsource-tc-server-edition directory, where edition refers to the Edition of tc Server you are using (node, developer, or standard.)

No.
-p --ports Colon-separated list of port numbers that should be configured in the catalina.properties file. Use this option if you do not want to use the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps.

This is an all-or-nothing option: you either list all four port numbers, in the correct order, or you list none at all. The order of port numbers is as follows: shutdown, http, ajp, jmx. For example, assume the following value:

--ports=8888:9999:6627:8727

The script would create the following in the catalina.properties file:

  • shutdown.port=8888

  • http.port=9999

  • ajp.port=6627

  • jmx.port=8727

Separate the four port numbers with colons.

Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers.

No.
-r

-r path_to_jre

--jrehome

--jrehome path_to_jre

If specified without a path_to_jre value, hard-codes the JRE_HOME variable in various files of the instance, using the global JRE_HOME environment variable value. You can also use this option to specify a different location of the Java runtime environment (JRE.) In this case, replace path_to_jre with the full pathname of the JRE.

If you do not specify this option at all, then the instance uses the JRE_HOME global environment variable, and does not hard-code the value anywhere.

The tcruntime-instance.sh script includes options for setting the path to a JDK (i.e. JAVA_HOME) and the path to a JRE (i.e. JRE_HOME). Typically, JAVA_HOME points to any valid location of a JVM or JRE, whereas JRE_HOME points only to a JRE. For most use cases, setting the JAVA_HOME variable by using the -j option is adequate and you do not need to set JRE_HOME with this option as well.

No.
-s serverName --server serverName Replaces serverName with the name of your new tc Runtime instance. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.Yes.
-t template_location --template template_location Applies a template to a newly-created tc Runtime instance.

In this context, a tc Runtime template refers to a set of customized tc Runtime files that the tcruntime-instance script copies to the instance it just created. An instance of tc Runtime itself can act as a template. The template files are organized in the standard Tomcat hierarchy; for example, configuration files are in the conf directory and binary files are in the bin directory. When the tcruntime-instance script applies the template after it has created a new instance, it might replace standard Tomcat files, depending on the contents of the template. For example, the template might replace the standard server.xml file with a new one, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

Replace the template_location argument with one of the following values:

  • Name of an existing subdirectory of the INSTALL_DIR/springsource-tc-server-edition/templates directory, where edition refers to the Edition of tc Server you are using ( node, developer, or standard.)

  • Absolute path to a directory that contains a tc Runtime template, such as /home/templates/tcserver/mytemplate.

  • Absolute path to a directory that contains a tc Runtime instance, such as /home/tcserver/springsource-tc-server-developer/spring-insight-instance.

  • File that contains a list of absolute template directories. If you specify a file, the tcruntime-instance script applies the template files in the order listed, which means if each template includes a file with the same name, the one in the last template takes priority.

For additional details and examples about this using feature, and information about creating your own templates, see Creating a tc Runtime Instance with a Template and Creating tc Runtime Templates.

No.
-v version --tomcatver version Pins the instance to the specified version of tc Runtime, such as 6.0.25.A-RELEASE. See Pinning a tc Runtime Instance to a Specific Version for a discussion of pinning.

Valid values depend on the versions of tc Runtime that you have installed. The tcruntime-instance.sh script determines the list of available versions by searching for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as 6.0.25.A-RELEASE. Use the -h option of the tcruntime-instance.sh script to see the list of known tc Runtime versions; the list is outputted in the information about the -v option.

If you do not specify this option, the instance is unpinned to a tc Runtime version, which means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script searches for the highest version and applies it to the instance. For example, if 6.0.24.A-RELEASE, 6.0.24.B-RELEASE and 6.0.25.A-RELEASE are all present, and you don't specify this option, then the start script automatically picks 6.0.25.A-RELEASE as the version of the instance. See Pinning a tc Runtime Instance to a Specific Version for more information.

No.

For example, to request that you be prompted for port numbers and that the tc Runtime installation directory is /home/tcserver/springsource-tc-server-node, run the following:

prompt$ ./tcruntime-instance.sh -s myserver -j /home/java/jdk1.6.0_12 -d /home/tcserver/springsource-tc-server-node -i

The following example shows how to modify an existing tc Runtime instance called myotherserver to use version 6.0.25.A-RELEASE of tc Runtime; the resulting instance will be pinned to this version:

prompt$ ./tcruntime-instance.sh -s myotherserver -m -v 6.0.25.A-RELEASE 

Pinning tc Runtime Instances to a Specific Version

Depending on whether you explicitly specify the -v version parameter of the tcruntime-instance.sh|bat script when you create an instance, the resulting tc Runtime instance is either pinned or unpinned to a particular version of tc Runtime. Specifically:

  • If you explicitly specify the -v version parameter, the tc Runtime instance is pinned to that version. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the instance always uses this tc Runtime version, even if you have installed a more recent version of the tc Runtime.

  • If you do not specify the -v version parameter, the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script searches for the most recent version of tc Runtime and applies it to the instance.

Use the -h parameter of tcruntime-instance.sh|bat to list the known tc Runtime versions.

For example, if you create a new instance using the following command:

prompt$ ./tcruntime-instance.sh -s myserver -v 6.0.25.A-RELEASE

the myserver instance will always use version 6.0.25.A-RELEASE of the tc Runtime, even if a more recent version is installed. If, however, you do not specify the -v parameter, for example:

prompt$ ./tcruntime-instance.sh -s myserver 

the myserver instance always uses the latest version of tc Runtime that is currently installed. Thus if you later install a new version of tc Runtime (which means that there will be a new tomcat-6.0.X.X-X directory alongside the existing ones), and start the unpinned myserver instance using the tcruntime-ctl.sh|bat script, the instance automatically uses the latest tc Runtime version without your having to explicitly do anything.

To determine whether an existing tc Runtime instance is pinned, check for the file INSTANCE-DIR/conf/tomcat.version; if the file exists, then the instance is pinned to the version specified in the file.

To change the version of a pinned instance, use the -m parameter together with -v to specify the new version. For example:

prompt$ ./tcruntime-instance.sh -s myserver -m -v 6.0.26.A-RELEASE

Finally, if you want to convert a currently pinned instance to one that is unpinned, use the -m parameter without -v. For example:

prompt$ ./tcruntime-instance.sh -s myserver -m 

Best Practice: Naming tc Runtime Instances

The name of a tc Runtime instance is the name of its CATALINA_BASE directory, minus the leading directory paths. As a reminder, CATALINA_BASE is the base directory of the instance; this directory contains the instance-specific startup scripts in the bin sub-directory, the configuration files in the conf sub-directory, and so on. For example, if you create a tc Runtime instance in the /home/tcserver/springsource-tc-server-node/myServer directory, then its name is myServer.

The HQ user interface also uses this naming convention when first identifying a tc Runtime instance. In particular, the HQ user interface displays an instance with the name platform-resource tc Runtime catalina-base-dir , where platform-resource refers to the computer on which the tc Runtime instance is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames. The HQ user interface uses the full pathname of CATALINA_BASE as the default description of the instance.

This means, however, that if you create two instances whose full pathnames differ, but their main installation directory names are the same, the instances will show up in the HQ user interface with the same names. This makes it difficult to differentiate multiple tc Runtime instances from each other, although you can always look at the description for the full pathname. For example, assume you have two instances in the following directories running on a computer identified as my-desktop in HQ:

  • /home/tcserver1/springsource-tc-server-node/myServer

  • /home/tcserver2/springsource-tc-server-node/myServer

Although they are completely different instances, they will both show up in the HQ user interface with the name my-desktop tc Runtime myServer.

For this reason, SpringSource recommends as a best practice that you use unique names for the main installation directory for each tc Runtime instance on the same computer. For example, the following two instances will show up in the HQ user interface with different names:

  • /home/tcserver1/springsource-tc-server-node/myServer

  • /home/tcserver2/springsource-tc-server-node/myOtherServer

Creating a tc Runtime Instance with a Template

To use the tcruntime-instance script to create a new tc Runtime instance with a template, use the -t (or --template) option. A template is simply a directory that contains additional or customized tc Runtime instance files, such as server.xml or JAR files. For example:

prompt$ ./tcruntime-instance.sh -s myserver -t cluster-node

An existing instance of tc Runtime can itself be used as a template.

When you specify the -t option, the tcruntime-instance script first creates the tc Runtime instance as usual, which mostly entails copying over the standard Tomcat files from the tomcat-version directory to the new instance directory, where version refers to the version of tc Runtime, such as 6.0.25.A-RELEASE. After the script creates a standard tc Runtime instance, it copies over the files and subdirectories contained in the specified tc Runtime template.

To use this feature, a template must already exist. You can create your own template, as described in Creating tc Runtime Templates, use one of the out-of-the-box templates, or even use an existing tc Runtime instance.

The files that make up a template reside in a single directory and 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. If you create a template, you can create additional subdirectories. When the tcruntime-instance script applies the template after it has created a new tc Runtime instance, it copies over all the files, including those in subdirectories. 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 replace the standard server.xml file with a new customized file, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

The argument to the -t option must be a template directory, an existing tc Runtime instance (which itself can act as a template), or a file that lists multiple template directories. If the template argument is a single name, the tcruntime-instance script assumes the template directory is located in the INSTALL_DIR/springsource-tc-server-edition/templates directory, where edition refers to the Edition of tc Server you are using (either node, developer, or standard.) You can also use an absolute directory name to specify a template directory in another location or an existing tc Runtime instance.

If you specify a file as an argument, the file must contain a list of absolute template directories. This feature enables you to easily apply multiple templates when creating a new instance. The tcruntime-instance script applies each template in order, first to last. This means that if each template contains a file with the same name and location, then only the last file actually takes priority because the first ones are copied over with files from subsequent templates.

The following example shows how to create a new tc Runtime instance called myserver using the cluster-node out-of-the-box template:

prompt$ ./tcruntime-instance.sh -s myserver -t cluster-node

In the preceding example, because it does not specify the -v or -j options, the instance is unpinned, and thus uses the latest installed version of tc Runtime, and the instance uses the value of JAVA_HOME in the environment.

The following example shows how to create a new tc Runtime instance called myserver using a custom template called my-super-template that is located in the templates directory:

prompt$ ./tcruntime-instance.sh -s myserver -t my-super-template

The following example shows how to create an instance using a template located in the directory /home/templates/tcserver/mytemplate:

prompt$ ./tcruntime-instance.sh -s myserver -t /home/templates/tcserver/mytemplate

The Developer Edition of tc Server includes a pre-created instance called spring-insight-instance; the instance is located in the INSTALL_DIR/springsource-tc-server-developer directory. The instance includes the Spring Insight feature. The following example shows how you can create a new tc Runtime instance using this existing instance:

prompt$ ./tcruntime-instance.sh -s myserver -t /home/tcserver/springsource-tc-server-developer/spring-insight-instance

The following example shows how to create an instance that uses multiple templates by specifying a file (templates.txt) that lists the templates; each template is listed with an absolute pathname, as shown after the example:

prompt$ ./tcruntime-instance.sh -s myserver -t templates.txt

The templates.txt file in turn contains a list of absolute template names:

/home/templates/tcserver/mytemplate
/home/templates/tcserver/myothertemplate

Templates Provided by tc Runtime

SpringSource tc Runtime provides a number of 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.

Additionally, the Developer Edition of tc Server also provides an out-of-the-box instance called spring-insight-instance in the INSTALL_DIR/springsource-tc-server-developer directory. This instance includes the Spring Insight feature, and is ready to use as soon as you install the Developer Edition of tc Server. You can also use the instance as a template if you want to create new instances that are automatically configured with Spring Insight.

The following example shows how to use the cluster-node out-of-the-box template to create a tc Runtime instance that is automatically configured as a cluster node:

prompt$ ./tcruntime-instance.sh -s myserver-clustered -t cluster-node

Because the cluster-node template is in the templates directory, you simply specify its name at the -t 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 template.) All templates are located in the INSTALL_DIR/springsource-tc-server-edition/templates, where edition refers to the edition of tc Server you installed (node, developer, or standard.)

Table 7.2. Out-of-the-Box Templates Provided by tc Runtime

Template NameComparison with Default tc Runtime Instance
apr-with-ssl

Differs as follows from the default tc Runtime instance:

  • A server.xml modified as follows:
    • An added APRLifecycleListener to detect the APR-based native library required to use the APR/native connector.
    • Uses the APR/native (APR) connector for HTTP.
    • An added APR HTTPS connector.
  • Sample certificate and key files for testing the SSL configuration.

    Warning: These sample certificates and key files are provided only to aid testing and debugging; they are not for production use. You must replace them with your own generated certificates and keys before moving to a production system.

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 and SSL Configuration HOW-TO on the Apache Tomcat Web site.

bio-with-ssl

Differs as follows from the default tc Runtime instance:

  • Modified server.xml that includes a Blocking IO (BIO) HTTPS connector.
  • Sample JKS keystore for testing the SSL configuration.

    Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system.

For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site.

cluster-node

Differs as follows from the default tc Runtime instance:

  • Addition of 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.
  • Addition of 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.

For more information, see Clustering/Session Replication HOW-TO on the Apache Tomcat Web site.

diagnostics

Differs from the default tc Runtime instance as follows:

  • Sample JDBC resource configuration that integrates with the request diagnostics to report slow queries.
  • ThreadDiagnosticsValve has been configured at the Engine level to report on slow running requests.
jmx-over-ssl

Differs from the default tc Runtime instance as follows:

  • Modified server.xml that uses SSL for all JMX communication.
  • Sample JKS keystore that can be used to test the JMX over SSL configuration.

    Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system.

For more information, SSL Configuration HOW-TO on the Apache Tomcat Web site.

nio-with-ssl

Differs from the default tc Runtime instance as follows:

  • A modified server.xml that uses the Non-Blocking IO (NIO) connector for HTTP and includes an NIO HTTPS connector.
  • A sample JKS keystore that can be used to test the SSL configuration.

    Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system.

For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site.


Creating tc Runtime Templates

You can create your own templates that include customizations that you can then use later to create new customized tc Runtime instances.

  1. Create a directory in INSTALL_DIR/springsource-tc-server-edition/templates, where edition refers to the edition of tc Server you are using(node, developer or standard). Name the directory the name you will give to the template itself.

    [Note]Note

    Although not required, SpringSource recommends that you create new templates in the templates directory so you can keep all your templates together. In this procedure it is assumed that you are going to create new templates in the templates directory.

  2. For each tc Runtime file you want to customize, create the subdirectory in which it lives and then create the customized file in that subdirectory.

    For example, to create a customized server.xml, create the file in the conf subdirectory of the new template directory. If you want to add a new shell script, add it to the bin directory.

    You can also create your own subdirectories that will be copied to the new instance. You can also add application JAR files to the webapps directory if you want these applications to be automatically deployed each time you start the instance.

    Warning: Do not modify (and thus include in your template) the bin/tcruntime-ctl.sh|bat file. If you do, the template may break in future versions of tc Runtime.

  3. To use the template, specify its name at the -t option of the tcruntime-instance.sh|bat script. See examples in Creating a tc Runtime Instance Using a Template.

The following file listing shows an example of a template called my-super-template; use it as a guide when creating your own templates. (You can also look at the out-of-the-box templates in the templates directory.) Note that the following sample template customizes the standard conf/context.xml and conf/server.xml files, adds JAR files to the lib and webapps directory and creates a new subdirectory (webapps-lib, alongside webapps), among other things:

my-super-template/lib/myapp_core-1.0.0.jar
my-super-template/lib/spring-instrument-classloading-3.0.0.BUILD.jar
my-super-template/deployToTomcat.sh
my-super-template/webapps-lib/myapp-springweb-1.0.0.jar
my-super-template/webapps-lib/myapp-springcore-1.0.0.jar
my-super-template/webapps-lib/myapp-jdbc-1.0.0.jar
my-super-template/webapps/myapp.war
my-super-template/conf/context.xml
my-super-template/conf/server.xml
my-super-template/conf/myapp.yml
my-super-template/instrument-tomcat.xml

Creating Portable tc Runtime Instances

A portable tc Runtime instance is one whose instance directory you can copy to a new directory name, and the instance still starts and works correctly without your having to update the instance configuration files.

To guarantee the portability of a newly-created tc Runtime instance, specify only the one required option of tcruntime-instance.sh|bat: -s serverName. Use the INSTANCE-DIR/bin/tcruntime-ctl.sh|bat script to start and stop the instance.

For example, assume you created a tc Runtime instance called myserveCcr in the main tc Server installation directory:

prompt$ cd /home/tcserver/springsource-tc-server-node
prompt$ ./tcruntime-instance.sh -s myserver

Because this instance is completely portable, you can copy the resulting instance directory to another location, and then start and use this new instance as if you had created it with the tcruntime-instance script. For example, assume you want to copy the myserver instance to the /home/tcserver/instances directory and call it myserver-new:

prompt$ cd /home/tcserver/springsource-tc-server-node
prompt$ cp -r myserver ../instances/myserver-new
prompt$ cd ../instances/myserver-new/bin
prompt$ ./tcruntime-ctl.sh start

Important: Remember that when you copy an instance in this way, the ports that the two tc Runtime instances listen to will be the same. If you want to run both instances on the same computer, update the conf/catalina.properties file of one instance to differentiate the port name.

Possible Exceptions to Portability of a tc Runtime Instance

If you originally specified additional options of the tcruntime-instance.sh|bat script when you created the first tc Runtime instance, the instance is not guaranteed to be portable. However, depending on the environment of the location to which you copy the instance, the copied instance might still start and work correctly without your having to update any of its configuration files. In particular:

  • If you originally specified the -j or -r options, then the tcruntime-instance.sh|bat script hardcoded the specified JDK or JRE path, respectively, in the resulting instance. If the copied instance would still use the same exact JDK or JRE path, then the instance is portable; otherwise, the instance will not start unless you modify this hardcoded JDK or JRE path.

  • Similarly, if you originally specified the -d option, the tcruntime-instance.sh|bat script hardcoded the location of the tc Server installation directory in the resulting instance. If you copy the instance to another location where the installation directory is still ../.., then the copied instance starts correctly.

  • If you specified the -v option to pin the tc Runtime instance to particular version of tc Runtime, the tcruntime-instance.sh|bat script created a file called conf/tomcat.version that specifies the version to which it is pinned. If you copy the instance to another location, it starts only if the corresponding tc Server installation also includes the exact version of the tc Runtime to which the instance is pinned.

    For example, if the file contains the string 6.0.25.A-RELEASE, then the tc Server main installation must contain a directory called tomcat-6.0.25.A-RELEASE.