Creating a New tc Server Instance

The following sections describe how to create new instances of tc server for each of the two types of layouts: SpringSource and ASF:

See Differences between the SpringSource and ASF Layouts of tc Server for details about the differences between these two layouts.

If you want to use the SpringSource layout of tc Server, then you are required to create a new instance because the out-of-the-box installation of tc Server does not automatically provide one for you. If, however, you want to use the ASF (or standard Apache) directory layout, then an instance already exists as soon as you install tc Server. Therefore, the ASF section below describes how to create a new instance in additional to the default out-of-the-box one.

NOTE: Each topic covers both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platorm, change these to back slashes (\).

Creating Instances in the SpringSource Layout

This section describes how to create a new tc Server instance when using the SpringSource layout.

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

  2. Change to the INSTALL_DIR/tcServer-6.0 directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver. This directory also contains the script for creating a new instance, tcserver-instance.sh (Unix) and tcserver-instance.bat (Windows). For example:

    prompt$ cd /home/tcServer/tcServer-6.0
  3. Run the tcserver-instance.sh (Unix) or tcserver-instance.bat (Windows) script, passing it the following required parameters at a minimum:

    • -s serverName : Replace serverName with the name of your new tc Server instance. See Best Practice: Naming tc Server Instances for tips on naming an instance.
    • -j path_to_jdk : Replace path_to_jdk with the full pathname of your installed JDK. NOTE: This parameter is not required if you have set the JAVA_HOME variable in your environment to point to the JDK.

    For example, on Unix:

    prompt$./tcserver-instance.sh -s myserver -j /home/java/jdk1.6.0_12

    When the script completes, the new server instance is located by default in the INSTALL_DIR/tcServer-6.0/myserver directory. This directory is also the value of the CATALINA_BASE variable for this server instance. The tc Server instance uses the JDK located in the /home/java/jdk1.6.0_12 directory. Additionally, the ports of the server instance are the default values, as follows:

    • HTTP listen port: 8080
    • JMX port: 6969
    • AJP port: 8009
    • Shutdown port: -1

    The version of the tc Server instance is the highest version that the script finds in the installation directory, for example 6.0.20.C.

    You can specify additional optional parameters of the tcserver-instance.sh script, as described in tcserver-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 server 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.

tcserver-instance.sh Reference

The following table lists all the available options of the tcserver-instance.sh|bat command.

There are two ways to specify each option; both are completely equivalent. The way you chose is completely up to you based on your preference. You can specify an option with a single dash and a letter (such as -s) or two dashes and a word (such as --server). The following table shows both ways of specifying the options.

Option (Single Dash) Option (Double Dash) Description Required?
-s serverName --server serverName Replace serverName with the name of your new tc Server instance. See Best Practice: Naming tc Server Instances for tips on naming an instance. Yes.
-v version --tomcatver version Replace version with the version of the new tc Server instance, such as 6.0.20.C.

The valid values of this option depend on the versions of tc Server that you have installed. The tcserver-instance.sh script determines the list of available versions by searching for tomcat-XXX directories, where XXX follows a pattern such as 6.0.20.C. Use the -h option of the tcserver-instance.sh script to see the list of known tc Server versions; the list is outputted in the information about the -v option.

If you do not specify this option, the tcserver-instance script picks the highest version of tc Server it can find in the installation directory. For example, if 6.0.19.A, 6.0.20.A and 6.0.20.C are all present, and you don't specify this option, then the script automatically picks 6.0.20.C.

No.
-j path_to_jdk --javahome path_to_jdk Replace path_to_jdk with the full pathname of your installed JDK. The default value of this option is the value of the JAVA_HOME environment variable.

The tcserver-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 to just a JRE. For most use cases, setting the JAVA_HOME variable by using this option is adequate and you do not need to set JRE_HOME with the -r option as well.

Only required if you have not set the JAVA_HOME variable in your environment to point to the JDK.
-r path_to_jre --jrehome path_to_jre Replace path_to_jre with the full pathname of your installed Java runtime environment (JRE). The default value of this option is the value of the JRE_HOME environment variable.

The tcserver-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 to just 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.
-d tcServerDir --tcserverdir tcServerDir Replace tcServerDir with the full pathname of the tc Server installation. Use this parameter if you are running the tcserver-instance.sh script from a location other than its default home directory. The default value of this parameter is the current working directory. Only required if you are not running the tcserver-instance.sh from its default location: INSTALL_DIR/tcServer-6.0.
-n instanceDir --instancedir instanceDir Replace instanceDir with the full or relative pathname of the directory in which you want the new tc Server instance to be created. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcserver-instance.sh|bat script.

If you do not specify this option, the tcserver-instance.sh|bat script creates the new instances in the INSTALL_DIR/tcServer-6.0 directory.

No.
-t template_location --template template_location Use this option to apply a template to a newly-created tc Server instance.

In this context, a tc Server template refers to a set of customized tc Server files that the tcserver-instance script copies to the instance it just created. 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 tcserver-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:

  • The name of an existing sub-directory of the INSTALL_DIR/tcServer-6.0/templates directory.
  • An absolute path to a directory that contains a tc Server template, such as /home/templates/tcServer/mytemplate.
  • A file that contains a list of absolute template directories. If you specify a file, the tcserver-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 Server Instance Using a Template and Creating tc Server Templates.

No.
-f --force Forces the script to create a new server instance, even if one already exists. By default the script does not force the creation.

If you specify this parameter against an existing server instance, the script replaces only the existing bin and conf directories; the script does not replace the other directories, such as lib or temp. This is because 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 want to leave the user-specific files, such as Web applications, alone.

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 above.

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

No.
-p --ports Specifies the 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 above.

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 you specifed the following value for this option:

--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 Server instances on the same computer have unique port numbers.

No.
-c --create Specifies that you want the tcserver-instance.sh script to create a new tc Server instance.

This is the default mode of the script.

No.
-m --modifyver Use this option to modify the version of tc Server that an existing tc Server instance uses.

You use this option together with the -s serverName option to specify the tc Server instance you want to modify and with the -v version option to specify the new version of the instance. If you do not explicitly specify -v version on the command line, the tcserver-instance script uses the default value of -v, which is the highest version it can find.

Note: You can use this option only against an existing tc Server instance; you cannot use this option when creating a new instance. It is assumed that you have already installed the tc Server version to which you want to modify the existing instance.

No.
-a arch --architecture Windows only. Specifies whether you want the tcserver-instance.bat script to create a 32-bit or 64-bit version of the Windows service wrapper.

Valid values are win32 and winx86_64. The default value is win32.

If you specify winx86_64 for this option, the Windows computer on which tc Server is installed must use a 64-bit operating system; note that tc Server supports only x86 64-bit architecture, not the Itanium 64-bit. Additionally, you must specify that the tc Server instance use a 64-bit JVM (with either the -j or -r option of the tcserver-instance.bat command). Similarly, if you specify win32 (default value), then you must specify a 32-bit JVM.

No.
-l --list Lists all the server 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.
-h --help Outputs information about all the available options of tcserver-instance.sh|bat. No.

For example, to request that you be prompted for port numbers and that the tc Server installation directory is /home/tcserver/tcServer6.0, run the following:

prompt$./tcserver-instance.sh -s myserver -v 6.0.20.C -j /home/java/jdk1.6.0_12 -d /home/tcserver/tcServer6.0 -i

The following example shows how to modify an existing tc Server instance called myotherserver to use version 6.0.20.C:

prompt$./tcserver-instance.sh -s myotherserver -m -v 6.0.20.C 

Best Practice: Naming tc Server Instances

The name of a tc Server 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 Server instance in the /home/tcserver/tcServer-6.0/myServer directory, then its name is myServer.

The AMS Console also uses this naming convention when first identifying a tc Server instance. In particular, AMS displays an instance with the name platform-resource tc Server catalina-base-dir, where platform-resource refers to the computer on which tc Server is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Server instance without the leading directory pathnames. The AMS console 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 AMS console with the same names. This makes it difficult to differentiate multiple tc Server 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 AMS:

Although they are completely different instances, they will both show up in AMS with the name my-desktop tc Server myServer.

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

Creating a tc Server Instance Using a Template

When you create a new tc Server instance using the tcserver-instance script, you can use the -t (or --template) option to specify a tc Server template. A template is simply a directory that contains additional or customized tc Server instance files, such as server.xml or JAR files. When you specify the -t option, the tcserver-instance script first creates the tc Server instance as usual, which mostly entails copying over the standard Tomcat files from the tcServer6.0/tomcat-version directory to the new instance directory, where version refers to the version of tc Server, such as 6.0.20.C. Then, after the script has created a standard tc Server instance, the script then copies over the files and sub-directories contained in the specified tc Server template.

To use this feature, a template must already exist. You can create your own template, as described in Creating tc Server Templates.

Templates are all contained in a single directory and are organized in the standard Tomcat sub-directory hierarchy. For example, configuration files live in the conf directory and JAR files live in the lib directory. If you are creating your own template, then you can also create additional sub-directories if you choose. When the tcserver-instance script applies the template after it has created a new tc Server instance, it copies over all the files, including those in sub-directories. Depending on the contents of the template directory, the new tc Server 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 either a template directory or a file that lists multiple template directories. If the template argument is just a single name, then the tcserver-instance script assumes the template directory is located in the INSTALL_DIR/tcServer-6.0/template directory. You can also use an absolute directory name to specify a template directory in another location.

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 tcserver-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 Server instance called myserver using a template called my-super-template that is assumed to live in the templates directory:

prompt$./tcserver-instance.sh -s myserver -v 6.0.20.C -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$./tcserver-instance.sh -s myserver -v 6.0.20.C -t /home/templates/tcServer/mytemplate

The following example shows how to create an instance using multiple templates by specifying a file that lists the template directories using absolute pathnames:

prompt$./tcserver-instance.sh -s myserver -v 6.0.20.C -t templates.txt

The templates.txt file would in turn contain a list of absolute template directory names:

/home/templates/tcServer/mytemplate
/home/templates/tcServer/myothertemplate

Creating tc Server Templates

To use the templating feature, you create your own templates with your own customizations which you can then use later to create new customized tc Server instances.

The template must be located in a single directory, and the name of the template is the name of the directory. SpringSource recommends that you create the templates in the INSTALL_DIR/tcServer-6.0/templates directory so you can keep all your templates together, although it is not required. Then, for each Tomcat file you want to customize, create the sub-directory in which it lives and then create the customized file in that subdirectory. For example, if you want to create a customized server.xml, create the file in the conf sub-directory. If you want to add a new shell script, add it to the bin directory. You can also create your own sub-directories that will be copied to the new instance. Finally, you can add application JAR files to the webapps directory if you want these applications to be automatically deployed each time the new instance is started.

The following file listing shows an example of a template called my-super-template; use it as a guide when creating your own templates. Note that the template customizes the standard conf/context.xml file and adds JAR files to the lib and webapps directory and creates a new sub-directory (webapps-lib, alongside webapps), amongst 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/myapp.yml
my-super-template/instrument-tomcat.xml

Creating Instances in the ASF Layout

The following procedure describes how to create a new tc Server instance when using the ASF layout.

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

  2. Run the main tc Server install program install.sh and install a new tc Server application server (option 3) into a new directory, different from the directory in which you installed the original tc Server application server. See Installing tc Server: Typical Steps.
  3. If you are going to run this tc Server instance on the same computer as another tc Server instance, you must ensure that the various port numbers are unique. You configure these ports in the INSTALL_DIR/tcserver-6.0/tomcat-version/conf/server.xml file, where INSTALL_DIR refers to the directory in which you just installed tc Server and version refers to the version of tc Server, such as 6.0.20.C. In particular, make sure the following ports are unique for each server instance:

    • The port and redirectPort attributes of the HTTP <Connector> child element of the catalina <Service>. These ports are the main tc Server listen and redirect ports.
    • The port attribute of the <Listener> element with classname com.springsource.tcserver.serviceability.rmi.JmxSocketListener. This is the JMX port that AMS uses to communicate with the tc Server instance so that you can manage it.

    NOTE: The server.xml file might use variable substitution for these ports; in this case the attribute looks something like port="${http.port}". If this is the case, edit the catalina.properties file in the same directory as the server.xml; the properties file contains actual values for the variables.