LATEST VERSION: 4.0 - CHANGELOG
Pivotal tc Server v4.0

Creating and Managing tc Runtime Instances

After you install Pivotal 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.

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 tcserver.properties Configuration Reference for more details.

Creating tc Runtime Instances with the tcserver Command Script

This section describes the simplest way to use the tcserver command script 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. On the computer on which you installed tc Server, log in as the user who will run tc Runtime instances, such as tcserver. On Unix, if you have disabled interactive login, log in as the root user and use su - tcserver to become the user.
  2. Be sure you have installed a JDK or JRE and have set your JAVA_HOME and PATH environment variables correctly. See Software Requirement: Install JDK or JRE.
  3. Open a terminal window (Unix) or Command Prompt (Windows).
  4. Change to the ${TCSERVER_HOME} directory, where ${TCSERVER_HOME} refers to the main tc Server installation directory, such as /opt/pivotal/pivotal-tc-server/standard-4.0.0.RELEASE:

    cd /opt/pivotal/pivotal-tc-server/standard-4.0.0.RELEASE
    
  5. Run the tcserver script, passing it the create instanceName option. Replace instanceName with the name of your new tc Runtime instance. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.

    This command should be ran as a user with permissions to write to the default instances directory.

    tcserver create instanceName 
    

When the preceding sample command completes, the new tc Runtime instance is located in the /var/opt/pivotal/pivotal-tc-server/standard/demo-instance directory This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance.

By default, the tc Runtime instance uses either the Java binaries pointed to by your JAVA_HOME environment variable or the java binary that it found in the PATH environment variable when it started. You can hard-code Java binaries that the tc Runtime instance uses by using the --java-home option.

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

  • HTTP listen port: 8080
  • JMX port: 6969\
  • Shutdown port: -1

The preceding tcserver sample did not specify the --version option, so the instance is pinned to the highest version (based on the preferred major version in tc Server) tc Runtime version located in the installation directory at creation time, for example 7.0.8.A.RELEASE. You can use the modify-version verb to change the version to which the instance is pinned. See Pinning tc Runtime Instances to a Specific Version for more information.

When you use the tcserver command script to create an instance, you can specify additional optional parameters, as described in tcserver Reference. For example, you can use the --property option to specify the Unix runtime user for the tc Runtime instance.

Pinning tc Runtime Instances to a Specific Version

You can use the --version parameter of the tcserver script to specify the version of tc Runtime to which the new instance is pinned. Specifically:

  • If you explicitly specify the --version parameter, the tc Runtime instance is pinned to that version. This means that when you use the tcrserver 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 --version parameter when you create the instance, it is pinned to the highest version available at the time the instance is created.(based on the preferred major version in tc Server).

To determine the list of available versions, search for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as 7.0.50.A.RELEASE.

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

tcserver create demo-instance --version 7.0.50.A.RELEASE 

the demo-instance instance will be pinned to version 7.0.50.A.RELEASE of the tc Runtime, even if a more recent version is installed. If, however, you do not specify the --version parameter, for example:

tcserver create demo-instance

the demo-instance instance is automatically pinned to the highest version available when the instance is created. Not having to explicitly specify a version when you create the instance is useful if you know that you simply want to use the highest available.

To determine the tc Runtime version to which existing instance is pinned, use the tcserver version command

tcserver version demo-instance

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

tcserver modify-version demo-instance --version 9.0.6.A.RELEASE 

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 /var/opt/pivotal/pivotal-tc-server/standard/demo-instance directory, then its name is demo-instance.

It is best practice to use unique names for the main installation directory for each tc Runtime instance on the same computer.

Differences Between the Separate and Combined Layouts

You can create two flavors of tc Runtime instances, depending on the layout of their files:

  • Separate layout: In this layout, the instance’s CATALINA_HOME and CATALINA_BASE point to two different directories. Typically, CATALINA_HOME points to a tomcat-9.0.X.RELEASE directory, which in turn contains the set of tc Runtime binaries that are shared by other instances that use the separate layout. This is the default layout.

    Pivotal highly recommends you use this layout because it provides for separation between the application specific files and the tc Runtime binaries. This eases the process of upgrading.

  • Combined layout: This layout closely resembles the standard Apache Tomcat layout where the instance’s CATALINA_HOME and CATALINA_BASE point to the same directory. This means that each instance that uses the combined layout has its own copy of the tc Runtime binaries. For this reason, it is very difficult to upgrade to a new version of tc Runtime.

    Pivotal does not recommend you use this layout, because it is so difficult to upgrade instances. The main reason for using it is if you are familiar with the Apache Tomcat layout and want to continue to use it in your environment.

Using the tc Runtime Templates

A template is simply a directory under the INSTALL-DIR/templates directory that contains additional or customized tc Runtime instance files. For example, the directory might contain a conf/server-fragment.xml file, which the tcserver 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 tcserver create command, or to the tcserver 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 tcserver script must exist in the tc Runtime template directory. The tcserver script looks for the template directory in the INSTALL_DIR/pivotal-tc-server/edition-version/templates directory, where edition-version refers to the edition of tc Server you are using (developer or standard) and the version of tc Server. Alternatively, as of tc Server 3.2, the template directory may be specified with --templates-directory.

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:

tcserver create --template nio demo-instance

In the preceding example, because it does not specify the --version or --java-home options, the instance uses the latest installed version of tc Runtime and the value of JAVA_HOME from the environment.

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

tcserver create demo-instance --template async-logger --template jmx-ssl

What the tcserver Script Does to Create a Runtime Instance

When you create a tc Runtime instance using tcserver, 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 script 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 tcserver script 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 script applies to the base instance. When the tcserver script 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:

tcserver 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.) All templates are located in the INSTALL_DIR/pivotal-tc-server/edition/templates, where edition refers to the edition of tc Server you installed (developer or standard).

Table 6. Out-of-the-Box Templates Provided by tc Runtime
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. When this template is applied, either the base-tomcat-7, base-tomcat-85, base-tomcat-8, etc is applied as well, depending on the tc Runtime version to be used by the instance.
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 Pivotal.

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.

async-logger

Configures asynchronous logging for the instance, which means that two separate tc Runtime threads handle incoming requests and write to the log file; by default, the same tc Runtime thread performs both actions. When you specify this template, the conf/logging.properties file contains references to the AsyncFileHandler class rather than the default FileHandler class.

After you specify asynchronous logging for an instance, you can configure its behavior by setting certain system properties in the CATALINA_BASE/bin/setenv.sh (Unix) or CATALINA_BASE/bin/setenv.bat (Windows) file. See the Configuring Asynchronous Logging section of the tc Server Administration Guide for details.

bio

Adds a Blocking IO (BIO) HTTP Connector to the new instance’s server.xml file.

Note: BIO connector was removed in tc Runtime 8.5

bio-ssl
  • Adds a Blocking IO (BIO) 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 Pivotal.

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

Note: BIO connector is only available for tc Runtime 7.0

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.

Note: When upgrading from an 8.0.x runtime to an 8.5.x runtime using the cluster-node template it is necessary to rename the MessageDispatch15Interceptor to MessageDispatchInterceptor in conf/server.xml

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.

Because this template does not specifically add a Connector to the instance’s server.xml file, the tcserver script automatically adds a Non-blocking IO (NIO) HTTP connector.

gemfire-cs

Provides fast, scalable, and reliable HTTP session replication for your tc Runtime instances, including support for the latest tc Runtime 8. This template applies to the client/server configuration of Pivotal GemFire.

Note: Only available for tc Runtime 7 and 8.5.

gemfire-p2p

Provides fast, scalable, and reliable HTTP session replication for your tc Runtime instances, including support for the latest tc Runtime 8. This template applies to the point-to-point configuration of Pivotal GemFire.

Note: Only available for tc Runtime 7 and 8.5.

jmx-ssl
  • Updates the JmxSocketListener to use SSL for all JMX communication
  • 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 Pivotal.

Because this template does not specifically add a Connector to the instance’s server.xml file, the tcserver script will automatically add a Blocking IO (BIO) HTTP Connector in tc Server 3.1.x and will add a Non-blocking IO (NIO) HTTP connector in tc Server 3.2.x.

For more information, see Additional Information About Using the SSL Templates).

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

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

redis-session-manager

Enables you to configure tc Runtime instances to use a Redis server for session management and replication. Does not require a user to specify a password to connect to Redis.

redis-session-manager-auth

Enables you to configure tc Runtime instances to use a Redis server for session management and replication. Requires a user to specify a password to connect to Redis.

Additional Information About Using the SSL Templates

If you specify one of the SSL templates (nio-ssl, apr-ssl, or jmx-ssl) when you create a tc Runtime instance, the tcserver script 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:

tcserver 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 tcserver 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 Pivotal 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 tcserver script or the Windows Services console to start and stop it.

Windows - Starting and Stopping tc Runtime Instances as Windows Services

By default, the tcserver script creates all tc Runtime instances under the INSTALL_DIR\pivotal-tc-server\edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as \opt\pivotal and edition is developer or standard. 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.

In the following procedure, it is assumed that you installed a tc Server Standard Edition.

To start and stop tc Runtime instances as Windows Services:

  1. Login to the computer on which you installed tc Server as the user who will run the tc Runtime instance, such as tcserver.
  2. 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.

  3. Install the tc Runtime instance as a Windows service:

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

    You should see a message indicating a successful installation:

    wrapper | Pivotal tc Runtime instance - tcserver-c-var-opt-pivotal-pivotal-tc-server-standard-demo-instance installed.

  4. Start and stop the tc Runtime instance using the tcserver script or the Windows Services console. The tc Runtime instance is displayed in the console with the name Pivotal tc Runtime instance - unique-name, where unique-name is a unique combination of server name and server directory.

    To start an instance using tcserver:

    tcserver start demo-instance
    

    To stop an instance using tcserver:

    tcserver stop demo-instance
    

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

```
tcserver uninstall demo-instance
```

Although Pivotal 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 Java Service Wrapper

On Windows, tc Runtime uses a Java Service Wrapper from Tanuki Software to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user logouts under Windows, service dependencies, and the ability to run services which interact with the desktop.

The wrapper is configured using the CATALINA_BASE\conf\wrapper.conf file, where CATALINA_BASE is the top-level directory of the tc Runtime instance, such as \var\opt\pivotal\pivotal-tc-server\standard\demo-instance. In most circumstances, you do not need to update this file because the default one created when you created the tc Runtime instance handles most use cases. However, you might sometimes want to further customize the Windows service to fit particular circumstances of your environment; in which case you can edit the wrapper.conf file.

For details about the configuration properties, see Configuration Property Overview.

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:

  1. From the Windows Start menu, open the Control Panel.
  2. Open Administrative Tools.
  3. Open the Local Security Policy tool.
  4. Expand the Local Policies settings.
  5. Click the User Rights Assignment.
  6. On the right side, double-click on the Log on as a service policy.
  7. 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

  1. Update the CATALINA_BASE/conf/tomcat-users.xml file in the tc Runtime instance by adding a manager-gui role (tc Runtime 7.0 or tc Runtime 8.0).

    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> 
    
  2. In the same file, add a user with the manager or manager-gui role, depending on your tc Runtime version.

    The user element for tc Runtime 7 or tc Runtime 8 looks like the following:

    <tomcat-users>
      <role rolename="manager-gui" />
      <user username="tomcat" password="tomcat" roles="manager-gui" />
    </tomcat-users> 
    
  3. Restart the tc Runtime instance for the changes to take effect.

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

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

Embedding tc Server

You can create an embedded server application with tc Server. In an embedded server application, the application is deployed and run as a JAR; the JAR file launches a main() method which in turn starts the server and deploys itself on it.

This section contains general instructions for embedding tc Server. For a working example, see Pivotal tc Server Embedded Example.

Prerequisites

  • Maven 2.2.1
  • The instructions below assume the existence of a Maven project into which you wish to embed tc Server.

Procedure

  1. Register an account at http://commercial-repo.pivotal.io
  2. Configure the repository in your project’s pom.xml (in the root of your project directory).
  3. Configure dependencies in your project’s pom.xml file.

    See Example pom.xml.

  4. Configure credentials for accessing the tcruntime-release package at build-time, as a server stanza in the Maven settings file (.m2/settings.xml).

  5. Run the build command to assemble the application with embedded tc Server and install it in your local Maven repository (.m2), located in your home directory.

  6. Start the application by invoking the executable jar created from the build.

Embedded Jars

Table 10. tc Server Embedded Jars

Group Id Artifact Id Description
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.embed.core Contains all of the core jars for tc Server embedded: catalina.jar, tomcat-coyote.jar,annotations-api.jar, tomcat-api.jar, tomcat-util.jar, servlet-api.jar
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.embed.jasper Contains all of the JSP classes: jsp-api.jar, jasper-el.jar, jasper.jar, el-api.jar
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.embed.logging.juli Contains the Juli logging classes: tomcat-juli.jar
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.embed.logging.log4j Contains the log4j logging classes: log4j.jar
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.embed.cluster Contains classes for clustering: catalina-ha.jar, catalina-tribes.jar
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.dbcp Contains classes for DBCP: tomcat-dbcp.jar
tcruntime.embed io.pivotal.tcserver.org.apache.tomcat.jdbc Contains classes for Tomcat JDBC: tomcat-jdbc.jar
tcruntime.embed io.pivotal.tcserver.org.eclipse.jdt.compiler Contains classes for Eclipse compiler: ecj-<version>.jar
tcruntime.embed io.pivotal.tcserver Contains the tc Server classes: tcServer.jar