Product Documentation. Pivotal tc Server. Version 3.x. Getting Started with Pivotal tc Server. Rev: Pivotal Software, Inc.

(1)

Pivotal

™

tc Server

®

Version 3.x

Getting Started with Pivotal tc Server

Rev: 03

(2)

Notice

Copyright

Pivotal Software, Inc. believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." PIVOTAL SOFTWARE, INC. ("Pivotal") MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any Pivotal software described in this publication requires an applicable software license.

(3)

(4)

Preface: Contacting Pivotal...vi

Current Pivotal Customers...vi

Public Inquiries About Application Fabric Products...vi

Chapter 1: About Getting Started with Pivotal tc Server...8

Intended Audience...8

Quick Start...8

Overview of tc Server... 10

Usability Enhancements to Apache Tomcat... 10

Easy Monitoring with the VMware vCenter Hyperic Agent Plug-In... 10

Agile Application Development with Spring Insight Developer...11

Application Cluster Monitoring with Spring Insight Operations...11

tc Server Editions... 12

Migrating Java EE Applications to tc Server...13

Contacting Pivotal

Current Pivotal Customers

Submit a ticket from the Help & Support Page.

Public Inquiries About Application Fabric Products

Email the appropriate group for the Application Fabric product: • [email protected]

• [email protected] • [email protected]

(7)

(8)

Chapter

1

About Getting Started with Pivotal tc Server

Getting Started with Pivotal tc Server describes product concepts and provides setup instructions for Pivotal tc

Server. Read the documentation to learn how to create, start, and stop tc Runtime instances; and deploy Web applications.

Intended Audience

This document is intended for anyone who wants to install, configure, and use tc Server to develop or to serve Web applications.

Quick Start

This section provides quick start instructions for installing Pivotal tc Server Standard Edition, creating a tc Runtime instance, and starting the tc Runtime instance.

If you are upgrading an existing tc Server installation, see the upgrade documentation. If you are installing tc Server Developer Edition, see Install tc Server Developer Edition.

Install tc Server

Note: This section provides instructions for installing tc Server Standard Edition from a ZIP file. On

a Windows machine, you could alternatively use the MSI installer.

1. Download and install a JDK or JRE on the computer on which you are installing tc Server. See

Supported Configurations and System RequirementsSupported Configurations and System Requirements.

2. Determine the user that is going to create and run the tc Runtime instances, and create it if necessary.

Consider creating a user dedicated to tc Server tasks and disabling its interactive login for security purposes. On Unix, never run tc Runtime instances as the root user. See Setting Up Unix Users for tc Server and VMware vCenter Hyperic.

For clarity, it is assumed in this topic that you will install and run tc Server as the tcserver user.

3. Login to the computer on which you are installing tc Server as the appropriate user, such as tcserver. If you have disabled interactive login, login as the root user and use su - tcserver to become the user.

4. Open a terminal (Unix) or Command Prompt (Windows) and create a directory to contain the tc Runtime

component (such as /opt/pivotal) if it doesn't already exist. Unix example:

prompt$ mkdir /opt/pivotal Windows example:

(9)

5. From the Pivotal tc Server product page, click Downloads.

6. Download the most recent pivotal-tc-server-standard-version.zip file and unzip the contents into the directory you created in the preceding step. The version in the zip file name is the release number, for example 3.0.2.RELEASE.

This is all that is required to install tc Runtime.

For example, in Unix, if you specified a directory called /opt/pivotal in the preceding step and downloaded the Standard Edition file to your home directory:

prompt$ cd /opt/pivotal

prompt$ unzip ~/pivotal-tc-server-standard-3.0.2.RELEASE.zip

In Windows Explorer, double-click the ZIP file you downloaded to launch the Windows Extraction Wizard and extract the file into the directory you created in the preceding step.

After you unzip the ZIP file you will have a directory called /opt/pivotal/pivotal-tc-server-standard-version . This directory contains all the tc Runtime files and directories.

Create and start a tc Runtime instance

1. From your terminal window or Command Prompt, change to the tc Runtime directory and execute the

tcruntime-instance command to create a basic tc Runtime instance (called myserver in the examples).

Pivotal recommends that you use the --instance-directory option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the tcserver user can write to this directory and that the directory already exists.

Unix example:

prompt$ cd /opt/pivotal/pivotal-tc-server-standard-3.0.2.RELEASE prompt$ ./tcruntime-instance.sh create --instance-directory /var/opt/ pivotal/pivotal-tc-server-standard myserver

Windows example:

prompt> cd \opt\pivotal\pivotal-tc-server-standard-3.0.2.RELEASE

prompt> tcruntime-instance.bat create --instance-directory \var\opt\pivotal-tc-server-standard myserver

2. Execute the tcruntime-ctl command to start the new tc Runtime instance; use the -i option to specify the directory in which the instance is located.

Unix example:

prompt$ ./tcruntime-ctl.sh myserver start -i /var/opt/pivotal/pivotal-tc-server-standard

Windows example:

prompt> tcruntime-ctl.bat myserver start -i \var\opt\pivotal\pivotal-tc-server-standard

To confirm that the tc Runtime instance is running, invoke its welcome page in a browser. Use the URL http://host:8080, where host is the name or IP address of the computer on which the tc Runtime instance is running (localhost if local).

What to do next

• Read about tc Server features

• Install tc Server Developer Edition

• Read about additional options for creating tc Runtime Instances, such as automatically configuring a NIO HTTPS connector or using Elastic Memory for Java (EM4J)

(10)

Overview of tc Server

Pivotal tc Server is a Web application server based on open-source Apache Tomcat. It preserves the best of Tomcat and adds many mission-critical operational capabilities that are unavailable in the open-source product. tc Server harnesses the power of traditional JEE architectures and eliminates their complexity and performance drawbacks, making it easier, faster, and more cost-effective to build and run cloud-ready applications. With its lean architecture and small memory footprint, tc Server requires significantly fewer resources than conventional servers, which allows for greater server density in virtual and cloud environments.

Subtopics

Usability Enhancements to Apache Tomcat

Easy Monitoring with the VMware vCenter Hyperic Agent Plug-In Agile Application Development with Spring Insight Developer Application Cluster Monitoring with Spring Insight Operations tc Server Editions

Migrating Java EE Applications to tc Server Related Documentation

Usability Enhancements to Apache Tomcat

The tc Server runtime component, known as tc Runtime, offers usability advantages that make it easier, faster, and more flexible to configure and operate than Apache Tomcat.

tc Runtime includes the following usability enhancements:

• Improved out-of-the-box configuration. In most cases, you can use tc Server immediately after you install it, with no additional configuration.

• Easy creation of a tc Runtime instance with the tcruntime-instance command script. You can leverage additional (optional) configuration features by specifying prepackaged templates when you create a tc Runtime instance, such as automatically configuring clustering or SSL.

• Easy and intuitive startup of a tc Runtime instance on both UNIX and Windows platforms. • Default configuration of high-concurrency JDBC connection pool in new tc Runtime instances.

Easy Monitoring with the VMware vCenter Hyperic Agent Plug-In

VMware vCenter Hyperic is a comprehensive enterprise application management tool.

Two versions of the Hyperic Agent plugin are available:

tc Runtime 8 Plugin

Pivotal provides a new Hyperic Agent plugin for tc Runtime 8 to monitor your instances of Pivotal tc Server on any computer, all Spring-powered applications, and a variety of other platforms and application servers such as Apache Tomcat using VMware vCenter Hyperic Server. Hyperic provides a single console with powerful dashboards from which you can easily check the health of your applications. The capability to manage tc Server instances is not available.

With Hyperic Server you can:

• Manage the lifecycle of tc Runtime instances by starting, stopping, and restarting local or remote instances.

(11)

In addition to the preceding tc Runtime-related actions, Hyperic performs these standard tasks: • Inventories the resources on your network.

• Monitors your resources.

• Alerts you to problems with resources. • Controls the resources.

tc Runtime 7 (version 2.9.x) Plugin

The legacy version 2.9.x Hyperic Agent plugin for tc Runtime 7 is also supported. This plugin provides management and monitoring capability.

With Hyperic Server, you can:

• Manage the lifecycle of tc Runtime instances by starting, stopping, and restarting local or remote instances.

• Similarly manage the lifecycle of a group of tc Runtime instances that are distributed over a network of computers.

• Configure a single instance of tc Runtime. Configuration options include the various port numbers to which the tc Runtime instance listens, JVM options such as heap size and enabling debugging, default server values for JSPs and static content, JDBC datasources, various tc Runtime connectors, and so on.

• Configure a group of tc Runtime instances using the tcsadmin command.

• Deploy a Web application from an accessible file system, either local or remote. You can deploy to both a single tc Runtime instance or to a predefined group of servers.

• Manage the lifecycle of applications deployed to a single tc Runtime instance or group of instances. Application lifecycle operations include start, stop, redeploy, undeploy, and reload.

In addition to the preceding tc Runtime-related actions, Hyperic performs these standard tasks: • Inventories the resources on your network.

• Monitors your resources.

• Alerts you to problems with resources. • Controls the resources.

For detailed information on using the Hyper Agent plugin to manage your tc Server instances, see the

VMware vCenter Hyperic documentation.

Agile Application Development with Spring Insight Developer

Spring Insight Developer, bundled with tc Server Developer Edition, makes it easy for application developers to observe the runtime behavior of Web applications. It allows you to see what is happening deep in the application, while it is running, with no required instrumentation. The visibility Spring Insight provides enables you to identify and solve problems quickly and to harden and tune the application by using readily available performance observations.

Application Cluster Monitoring with Spring Insight Operations

Spring Insight Operations enables administrators to monitor the real-time behavior and health of Web applications and the servers on which they are deployed. It gives the same deep visibility into applications as Spring Insight Developer, as well as the capability to view the information across a cluster or to drill down to any single server.

Whereas Spring Insight Developer runs within a single tc Server instance alongside the Web applications it analyzes, Spring Insight Operations has a distributed architecture. A single, dedicated tc Server instance runs the Spring Insight Dashboard. Each tc Server instance hosting applications in your cluster runs the Spring Insight Agent application. The Agents collect trace data and submit it to the Dashboard, where the

(12)

information is compiled and rendered. This design minimizes the overhead Spring Insight adds to your production servers and makes it easier to secure the Dashboard.

tc Server Editions

tc Server is available in three different editions. tc Server Developer is geared towards the enterprise application developer. tc Server Standard and Spring Edition are designed for operators and

administrators.

Table 1: Pivotal tc Server Editions

Feature Developer Edition Standard Edition Spring Edition

tc Runtime x x x

Spring Insight Developer x

VMware Hyperic with tc Server Plug-In x x

Spring Insight Operations x

Commercial Spring Support x

The following sections describe the tc Server editions: • Developer Edition

• Standard Edition

• Spring Edition

Developer Edition

The Developer Edition of tc Server is geared towards the application developer. It contains the tc Runtime; utilities to create and start tc Runtime instances; and a set of templates for creating specific preconfigured tc Runtime instances, such as cluster-node ready and SSL-enabled.

This edition also includes Spring Insight Developer, an application that provides real-time visibility into the behavior and performance of user applications. The tc Server Developer Edition contains a template called insight that includes the Spring Insight application. You use this template to create new tc Runtime instances enabled with Spring Insight. See About Spring Insight Developer for help setting up and using Spring Insight.

tc Server Developer Edition includes Tomcat Web Application Manager, a web application you can use to deploy and manage tc Runtime applications. This edition does not include access to Hyperic Server and Agent.

The Developer Edition is distributed as either a ZIP or compressed TAR file with the following names: • pivotal-tc-server-developer-version.RELEASE.msi

• pivotal-tc-server-developer-version.RELEASE.tar.gz • pivotal-tc-server-developer-version.RELEASE.zip

Standard Edition

The Standard Edition of tc Server is for administrators and operators. Similar to the Developer Edition, the Standard Edition contains the tc Runtime, scripts to easily create and start tc Runtime instances, and templates to quickly create specific types of tc Runtime instances (such as cluster-node ready or SSL-enabled). This edition does not include Spring Insight Developer.

(13)

With the Standard Edition, you have access to the vCenter Hyperic management system1, which (as of version 4.6) includes the tc Server Hyperic plug-in in the general distribution. Install vCenter Hyperic if you want to use Hyperic to configure and manage the tc Runtime. If you do not want to use Hyperic to manage tc Runtime instances and want to use the tc Runtime on its own, install only the tc Runtime.

The Standard Edition is distributed as either a ZIP or compressed TAR file with the following names: • pivotal-tc-server-standard-version.RELEASE.msi

• pivotal-tc-server-standard-version.RELEASE.tar.gz • pivotal-tc-server-standard-version.RELEASE.zip

Pivotal tc Server Standard Edition is also available as an RPM for customers installing on Red Hat Enterprise Linux (RHEL) and as a Debian package for customers installing on Ubuntu.

To download an evaluation of Hyperic, go to the Pivotal Downloads Center.

Spring Edition

The tc Server Spring Edition includes all of the components and features of tc Standard Edition, plus Spring Insight Operations and Spring commercial support.

Spring Insight Operations differs from Spring Insight Developer, which is included in the tc Server Developer Edition, in that it is designed to be used with an in-production system. It allows you to view real-time behavior and health of your production applications. You can see application behavior across all servers and drill down to see specific servers. With Spring Insight Operations, you create one tc Runtime Instance using the Insight Dashboard template. This instance contains the Spring Insight user interface. You create production tc Runtime instances with the Insight Agent template. The Agent template adds the ability to collect traces from your web applications and forward them to the Dashboard instance.

The tc Server Spring Edition is the same binary distribution as the Standard Edition, with licensing differences. The Spring Insight Operations Dashboard template is a separate download at the Pivotal download center. From the Pivotal tc Server product page, click Downloads.

Migrating Java EE Applications to tc Server

If you have Java EE applications you would like to migrate from another runtime to tc Server, you can use the Spring Migration Analyzer command-line tool to generate migration analysis reports that contain information about the APIs the application uses, and any migration tasks that might be necessary to run the application on tc Runtime.

You can download Spring Migration Analyzer from https://github.com/SpringSource/spring-migration-analyzer.

Installing Pivotal tc Server

Installation options vary according to whether your operating system is Linux or another supported platform. Installation also varies according to whether you are installing tc Server for the first time or are upgrading from a previous version.

Subtopics

Install tc Server Standard Edition From a ZIP or TAR File

Mac OS X: Install Pivotal tc Server Developer Edition as a Homebrew Brew on page 15

RHEL: Install tc Server Standard Edition From an RPM

Ubuntu: Install Pivotal tc Server from the Pivotal Debian Package Repository Windows: Install tc Server Standard or Developer Edition From the MSI Installer Install Hyperic Agent Plugin

Install tc Server Developer Edition From a ZIP or TAR File Overview of tc Server Directories, Variables, and Configuration Enabling Bash Completion for tc Server Scripts

Setting Up Unix Users for tc Server and Hyperic

Install tc Server Standard Edition From a ZIP or TAR File

Prerequisites

• Verify that your system meets the supported configurations and installation requirements. See

Supported Configurations and System Requirements.

• Review information about tc Server Standard edition and its *.zip or *.tar.gz distribution files. See

tc Server Editions.

• If you are installing from a *.tar.gz on a Solaris, make sure to use GNUtar to unpack the archive. • Determine the user that is going to create and run the tc Runtime instances, and create it if necessary.

Consider creating a user dedicated to tc Server tasks, putting the user in a separate group from regular users, and disabling its interactive login for security purposes. See Setting Up Unix Users for tc Server and Hyperic.

Attention:

On Unix, never run tc Runtime instances as the root user.

Procedure

2. Download the Standard Edition package distribution in ZIP or compressed TAR format to a directory on

your computer, for example /home/Downloads.

• pivotal-tc-server-standard-version.RELEASE.zip • pivotal-tc-server-standard-version.RELEASE.tar.gz

(15)

3. Log in to the computer on which you are installing tc Server as the appropriate user, such as

tcserver. On Unix, if you have disabled interactive login, login as the root user and use su -tcserver to become the user.

4. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation

directory, such as /opt/pivotal. For example, on Unix:

prompt$ mkdir /opt/pivotal

5. Extract the tc Server distribution file into the new directory.

This action installs tc Runtime; there is no installer program.

For example, if you created a directory called /opt/pivotal in the preceding step, and downloaded the Standard Edition ZIP file in the /home/Downloads directory:

prompt$ cd /opt/pivotal

prompt$ unzip /home/Downloads/pivotal-tc-server-standard-3.0.2.RELEASE.zip This action creates a directory called pivotal-tc-server-standard-version in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on.

What to do next

• For details about the directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files

• For typical post-installation procedures such as creating tc Runtime instances and starting tc Server components, see Creating and Managing tc Runtime Instances.

Mac OS X: Install Pivotal tc Server Developer Edition as a

Homebrew Brew

You can install Pivotal tc Server Developer Edition on Mac OS X computers using Homebrew.

Note: You may not be able to install the tc Server brew from inside a firewall.

Install Pivotal tc Server Developer Edition

Prerequisites

• Verify that your system meets the supported configurations described in Supported Configurations and System Requirements.

• Ensure that you have the latest brews. brew update

Procedure

1. Log in to the Mac OS X computer on which you will install Pivotal tc Server. 2. Execute the following brew commands:

brew tap pivotal/tap brew install tcserver

What to do next

• For details about the directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files.

(16)

• Run the following command to create a new tc Server instance in the current directory: tcruntime-instance.sh create <instance_name>

• Run the following command to create a new tc Server instance with Spring Insight monitoring: tcruntime-instance.sh create -t insight <instance_name>

• Run the following command to start a tc Server instance in current directory: tcruntime-ctl.sh <instance_name> start

RHEL: Install Pivotal tc Server Standard Edition from an RPM

Pivotal recommends that you install Pivotal tc Server (Standard Edition) on a Red Hat Linux Enterprise (RHEL) computer by first installing the Pivotal RPM repository and then using yum to perform the actual installation. See Install Pivotal tc Server from the Pivotal RPM Repository.

You can also download the RPM from the Pivotal download page and install it on your RHEL computer using the rpm command, as described in Install Pivotal tc Server from a Downloaded RPM.

Install Pivotal tc Server from the Pivotal RPM Repository

Pivotal recommends that you install tc Server on RHEL computers using the Pivotal RPM repository.

Prerequisites

• Set the JAVA_HOME environment variable in the root user's environment. For example, you could add the following line to /etc/profile and then open a new terminal window:

export JAVA_HOME=/usr/java/latest

Replace/usr/java/latest with the base directory of your JVM installation.

• Install the Pivotal repository RPM, which makes it easier for you to browse the Pivotal RPMs, including the Pivotal tc Server RPM. You install the Pivotal repository RPM on each RHEL computer on which you want to install one or more Pivotal products, such as Pivotal tc Server.

1. On the RHEL computer, start a terminal either as the root user or as an unprivileged user who has sudo privileges.

2. Install the Pivotal repository RPM using the following wget command, passing it the appropriate URL.

Important: Run the entire wget command on a single line. Be sure you include the | sh at the end, or the RPM installation fails.

prompt# wget -q -O - http://packages.pivotal.io | sh

Use sudo to run the preceding commands if you are not logged in as the root user. For example: prompt$ wget -q -O - http://packages.pivotal.io | sudo sh

The command performs the following tasks:

• Imports the Pivotal GNU Privacy Guard (GPG) key. • Installs the Pivotal repository RPM.

• Launches the Pivotal End User License Agreement (EULA) acceptance and repository configuration script.

• Outputs the EULA for you to read; you must answer yes to accept the terms and continue.

3. Use the yum search pivotal command to view the list of Pivotal components that you can install from the Pivotal repository. For example (output truncated for clarity):

(17)

prompt# yum search pivotal ...

======================================== Matched: pivotal ========================================

pivotal-rabbitmq-java-client-bin.noarch : The RabbitMQ Java Client Library pivotal-rabbitmq-server.x86_64 : The RabbitMQ server

pivotal-tc-server-standard.noarch : Pivotal tc Server Standard pivotal-web-server.x86_64 : Pivotal Web Server

...

The Pivotal tc Server RPM is called pivotal-tc-server-standard.

Procedure

1. From the RHEL computer on which you will install Pivotal tc Server, log in as the root user (or as an unprivileged user who has sudo privileges) and start a terminal.

2. Execute the following yum command:

prompt# yum install pivotal-tc-server-standard

The yum command begins the install process, resolves dependencies, and displays the packages it will install.

If necessary, use sudo to run the preceding command if you are not logged in as the root user. For example:

prompt$ sudo yum install pivotal-tc-server-standard

3. Enter y at the prompt to begin the actual installation.

If the installation is successful, you see a Complete! message at the end.

What the yum install command does

The yum install command:

• Installs Pivotal tc Server into the /opt/pivotal/pivotal-tc-server-standard directory and sets the owner of the directory, along with all child directories and files, to root:pivotal.

• If the user does not already exist, adds a tcserver non-interactive user (in the group pivotal). Pivotal recommends that you create and run tc Server instances as this user.

You cannot log in directly as the tcserver user because interactive login is disabled. Rather, you must log in as the root user or as a privileged user using sudo , and then su - tcserver .

• Creates an empty directory called /var/opt/pivotal/pivotal-tc-server-standard and sets the owner to tcserver:pivotal.

Pivotal recommends that you create new tc Server instances in this directory rather than the installation directory. You do this by specifying the -i option of the tcruntime-instance command.

What to do next

Install Pivotal tc Server From a Downloaded RPM

You can install Pivotal tc Server on RHEL by downloading the RPM from the Pivotal download center and executing the rpm command.

(18)

Prerequisites

Procedure

1. Log in to the RHEL computer on which you will install Pivotal tc Server as the root user (or as an unprivileged user who has sudo privileges).

3. Download the tc Server Standard Edition RPM file to a directory on your computer. The RPM file is

called pivotal-tc-server-standard-version-RELEASE.noarch.rpm.

4. Start a terminal and change to the directory in which you downloaded the RPM. 5. Execute the following rpm command to install tc Server:

prompt# rpm -ivhf pivotal-tc-server-standard-version-RELEASE.noarch.rpm If necessary, use sudo to run the preceding command if you are not logged in as the root user. For example:

prompt$ sudo rpm -ivhf pivotal-tc-server-standard-version-RELEASE.noarch.rpm

6. In the previous section, see What the yum install command does for post-installation information, such as the installation directory and the user that is automatically created by the RPM installation. (The yum install command corresponds to the rpm command in this procedure.)

See What to do next for the suggested next steps.

Ubuntu: Install Pivotal tc Server from the Pivotal Debian Package

Repository

It is recommended that you install Pivotal tc Server (Standard Edition) on a computer running Ubuntu by first installing the Pivotal Debian package repository and then using apt-get to perform the tc Server installation.

Prerequisites

• Install the Pivotal Debian package repository that contains the Pivotal tc Server *.deb packages.

1. On the Ubuntu computer, start a terminal either as the root user or as an unprivileged user who has sudo privileges.

2. Install the Pivotal Debian package repository using the following wget command:

Important: Run the entire wget command on a single line. Be sure you include the | sh at the end, or the installation fails.

prompt# wget -q -O - http://packages.pivotal.io/ | sh

If necessary, use sudo to run the preceding commands if you are not logged in as the root user. Use the following sudo command:

prompt$ wget -q -O - packages.pivotal.io/ | sudo sh The command performs the following tasks:

• Imports the Pivotal GNU Privacy Guard (GPG) key. • Installs the Pivotal Debian package repository.

• Launches the Pivotal End User License Agreement (EULA) acceptance and repository configuration script.

(19)

• Outputs the EULA for you to read; you must answer yes to accept the terms and continue.

3. Use the apt-cache search pivotal command to view the list of Pivotal components that you can install from the Pivotal Debian package repository. For example:

prompt# apt-cache search pivotal

pivotal-tc-server-standard - Commercial Java application server based on Apache Tomcat

pivotal-web-server - Pivotal Web Server

pivotal-web-server-devel - Pivotal Web Server Libraries and Headers

pivotal-repo-precise - Pivotal EULA and APT repo configuration utility...

Procedure

1. From the Ubuntu computer on which you will install Pivotal tc Server, log in as the root user (or as an unprivileged user who has sudo privileges) and start a terminal.

2. Execute the following apt-get command:

prompt# apt-get install pivotal-tc-server-standard

The apt-get command begins the install process, resolves dependencies, and displays the packages it will install.

If necessary, use sudo to run the preceding command if you are not logged in as the root user: prompt$ sudo apt-get install pivotal-tc-server-standard

What the apt-get install command does

The apt-get install command:

• Installs Pivotal tc Server into the /opt/pivotal/pivotal-tc-server-standard directory and sets the owner of the directory, along with all child directories and files, to root:pivotal.

• If the user does not already exist, adds a tcserver non-interactive user (in the group pivotal). It is recommended that you create and run tc Server instances as this user.

You cannot log in directly as the tcserver user because interactive login is disabled. Rather, you must log in as the root user or as a privileged user using sudo , and then su - tcserver .

• Creates an empty directory called /var/opt/pivotal/pivotal-tc-server-standard and sets the owner to tcserver:pivotal.

It is recommended that you create new tc Server instances in this directory rather than the installation directory. You do this by specifying the -i option of the tcruntime-instance command.

What to do next

Windows: Install tc Server Standard or Developer Edition Using

the MSI Installer

Prerequisites

• Review information about tc Server Standard Edition or Developer Edition. See tc Server Editions. For clarity, it is assumed in this topic that you will install and run tc Server as the tcserver user.

(20)

Procedure

2. Download the MSI installer distribution package for the Standard Edition or Developer Edition to a

convenient directory on your computer.

• pivotal-tc-server-developer-version.RELEASE.msi • pivotal-tc-server-standard-version.RELEASE.msi

3. Log in to the computer on which you are installing tc Server as the appropriate user, such as

tcserver.

4. Navigate to the directory where you downloaded the distribution package. 5. Double-click the MSI installer.

The Welcome page opens.

6. Click the Next button.

The End-User License Agreement page opens.

7. Read the text. If you agree, then accept the terms. 8. Click the Next button.

The setup type page opens. The page describes two setup types:

• Sample: All setup options are selected for you. This setup type is intended for potential customers who are evaluating the software. This option installs the tc Runtime to the default location and creates a sample instance called MyInstance with HTTP listening on port 8080. For more control over the installation choices, choose the Custom option instead.

a. Click the Sample button.

The setup options list page opens.

b. Review the list.

c. Click the Install button when you are ready to proceed.

• Custom: You can select all of the setup options.

a. Click the Custom button.

The Custom Setup page opens.

b. Choose to accept the default installation location for the application files, or browse and select a

different location on your local hard drive.

c. Click the Next button.

The Create Instance page opens. Complete the following fields:

• Enter a logical name for the instance. • Select the Apache Tomcat version to install.

• Select the Use Instance configuration file checkbox if you want to configure your new tc Runtime instance using a properties file.

• Configuration File: Browse to and select the location of the file containing properties that you

want to apply to the new tc Runtime instance.

When you create a properties file, it should contain one property per line in the form

template-name.property-name=value. The name of the property depends on the template. For example, the default template (called bio) has two configuration properties: http.port and https.port. Other templates might specify their own configuration properties. If you want to pass your own values of these properties to the tcruntime-instance script on the command line rather than accepting the default values, create a file with values such as the following:

(21)

bio.https.port=9191

Post-installation, see the configuration-prompt.properties file in the INSTALL_DIR/ pivotal-tc-server-edition-release/templates/template-name directory for the list of configuration properties that apply to a particular template.

• Instance Location: Accept the default instance location, or browse to and select a new

location.

• JAVA_HOME: Accept the default Java runtime engine location, or browse to and select a

different JRE directory.

d. Click the Next button.

A page listing available templates opens. Select from among the available templates to apply to your tc Runtime instance. You can apply multiple templates to the instance.

In this context, a tc Runtime template refers to a set of customized tc Runtime files copied to the instance.

For additional details and examples about using templates, see Templates Provided by tc Server

on page 46.

e. Click the Next button.

The setup options list page opens.

f. Review the list.

g. Click the Install button when you are ready to proceed. 9. The setup wizard:

• Installs tc Server

• Creates the initial tc Runtime instance

• Configures and starts the Microsoft Windows services.

What to do next

Uninstalling tc Server

The following options are available to uninstall tc Server:

• Click the Start button > All Programs > Pivotal > Uninstall Pivotal tc Server. • Uninstall Pivotal tc Server using the Programs control panel.

You can optionally remove all tc Runtime instances when you uninstall the application.

Install Hyperic Agent Plugin

Two versions of the Hyperic Agent plugin are available:

1. Download the Pivotal tc Server plugin from the Pivotal Network.

2. Rename the plugin file pivotal-tcserver-plugin.jar.

3. Install the plugin using the Hyperic Plugin Manager.

For instructions, see "Deploying and Managing Plug-ins" in the VMware vCenter Hyperic documentation.

(22)

1. Download the Pivotal tc Server plug-in 2.9.x for VMware Hyperic from Pivotal Network.

2. Complete the installation using the instructions found in the README file. The README is located

inside the plugin zip archive.

Install tc Server Developer Edition From a ZIP or TAR File

When you install the Developer Edition of tc Server, you also typically create a tc Runtime instance that contains Spring Insight Developer. The procedure covers Unix and Windows installation, although most instructions are specific to Unix. If you install on Windows, change the forward slashes (/) to back slashes (\); other differences in the installation are called out.

Prerequisites

• Review information about tc Server Developer edition and its *.zip or *.tar.gz distribution files. See

tc Server Editions.

• If you are installing from a *.tar.gz on a Solaris, make sure to use GNU tar to unpack the archive. • Determine the user that is going to create and run the tc Runtime instances, and create it if necessary.

Consider creating a user dedicated to tc Server tasks, putting the user in a separate group from regular users, and disabling its interactive login for security purposes. See Setting Up Unix Users for tc Server and Hyperic.

Attention:

On Unix, never run tc Runtime instances as the root user.

Procedure

2. Download the Developer Edition distribution in ZIP or compressed TAR file format.

• pivotal-tc-server-developer-version.RELEASE.zip • pivotal-tc-server-developer-version.RELEASE.tar.gz

3. Login to the computer on which you are installing tc Server as the appropriate user, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su - tcserver to become the user.

4. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation

directory, such as /opt/pivotal. For example, on Unix:

prompt$ mkdir /opt/pivotal

5. Extract the tc Server distribution file into the new directory.

This action creates a directory called pivotal-tc-server-developer-version in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on.

The templates directory contains a template called insight that contains the Spring Insight application.

6. Create a tc Runtime instance that contains Spring Insight by specifying the insight template.

Unix: Change to the /opt/pivotal/pivotal-tc-server-developer-version directory and execute the tcruntime-instance.sh script to create an instance.

(23)

Pivotal recommends that you use the -i option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the tcserver user can write to this directory and that the directory already exists.

For example:

prompt$ cd /opt/pivotal/pivotal-tc-server-developer-3.0.2.RELEASE prompt$ ./tcruntime-instance.sh create -t insight

-i /var/opt/pivotal/pivotal-tc-server-developer insight-instance

Windows: Change to the \opt\pivotal\pivotal-tc-server-developer-version directory and execute the tcruntime-instance.bat script to create an instance:

prompt> cd \opt\pivotal\pivotal-tc-server-developer-3.0.2.RELEASE prompt> tcruntime-instance.bat create -t insight

-i \var\opt\pivotal\pivotal-tc-server-developer insight-instance

7. Start the new tc Runtime instance.

Unix: Execute the tcruntime-ctl.sh script to start the instance; use the -i option to specify the directory in which the instance is located. For example:

prompt$ ./tcruntime-ctl.sh insight-instance start -i /var/opt/pivotal/ pivotal-tc-server-developer

Windows: Execute the tcruntime-ctl.bat script to first install the tc Runtime instance as a

Windows service and then start it; for both commands, use the -i option to specify the directory in which the instance is located:

prompt> tcruntime-ctl.bat insight-instance install -i \var\opt\pivotal \pivotal-tc-server-developer

prompt> tcruntime-ctl.bat insight-instance start -i \var\opt\pivotal \pivotal-tc-server-developer

Note:

On Windows, Pivotal recommends that you subsequently start and stop the tc Runtime instance through 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.

8. After the tc Runtime instance starts, invoke Spring Insight in your browser:

http://host:8080/insight

where host refers to the computer on which Spring Insight is running. If you are on the same computer, you can use localhost:

http://localhost:8080/insight

What to do next

• For details about the directories you installed, see Overview of tc Server Directories, Variables, and Configuration Files.

• For Spring Insight overview information and to create plug-ins that extend Spring Insight, see Spring

Insight Developer.

Overview of tc Server Directories, Variables, and Configuration

Files

When you install the tc Runtime component, you simply unpack the appropriate *.zip or *.tar.gz file into the main installation directory. This action creates a pivotal-tc-server-edition-version subdirectory, where edition-version refers to the edition of tc Server that you are using (standard or developer) and the version of tc Server. This subdirectory in turn contains the following tc Server-related files and directories:

(24)

• tomcat-.version Where version is the version of the core Apache Tomcat on which this version of the tc Runtime is based, such as tomcat-7.0.42.A.RELEASE or tomcat-7.0.50.A.RELEASE. These directories are the basic Apache Tomcat CATALINA_HOME directory. Standard Apache Tomcat users recognize its contents.

• templates. Out-of-the-box templates for creating customized tc Runtime instances, such as cluster-node enabled or SSL-ready. You can specify one or more of these templates when you run the

tcruntime-instance.sh|bat script to create a new tc Runtime instance. See Templates Provided by tc Runtime for the full list.

• lib . JAR files that implement the templating mechanism and are used by the tcruntime-instance script.

• tcruntime-instance.sh|bat . Scripts for creating new tc Runtime instances.

When you create a new tc Runtime instance with this script, the script creates the instance directory specified with the -i option or, by default, a subdirectory of the

pivotal-tc-server-edition-version directory with the same name as the new tc Runtime instance. This new directory is the CATALINA_BASE of the tc Runtime instance. The new directory contains the instance-specific configuration files, its own Web application deployment directory, log files, and so on.

• tcruntime-ctl.sh|bat. Scripts for controlling tc Runtime instances, such as start and stop scripts. The bin directories of individual tc Runtime instances include their own versions of these scripts that in turn call these main scripts. You can also call the top-level scripts if you specify the name of the tc Runtime instance.

• bash_completion. The bash_completion directory contains scripts to enable the bash completion capabilities for tcruntime-instance.sh and tcruntime-ctl.sh. If you use a bash shell on a Unix-like system and you have the bash-completion package installed, you can use the Tab key to complete command arguments and suggest alternatives when using these tc Server scripts. See

Enabling Bash Completion for tc Server Scripts for instructions on setting up this feature.

tc Server Variables

tc Server uses the following variables:

• CATALINA_HOME . Root directory of your tc Runtime installation.

The CATALINA_HOME variable points to the directory

INSTALL_DIR/pivotal-tc-server-edition-version/tomcat-version , where INSTALL_DIR is the directory in which you installed tc Server (such as /opt/pivotal); edition-version refers to the version and edition of tc Server you are using (developer-3.0.2.RELEASE or standard-3.0.2.RELEASE); and version is the version of the underlying Tomcat, such as 7.0.47.A.RELEASE.

• CATALINA_BASE . Root directory of a particular tc Runtime instance.

This directory contains the instance-specific files, such as the conf/server.xml file that configures this particular instance. If you created a tc Runtime instance called myserver and you are using the Standard Edition, then the CATALINA_BASE of the instance is INSTALL_DIR/pivotal-tc-server-standard-version/myserver by default.

The following variables are "exposed" by tc Runtime, which means that you can set them or use them in your environment (or in the bin/setenv.sh file of your tc Runtime instance) to achieve the specified results:

• CATALINA_OUT . Unix only. Use this environment variable to specify a file to which a tc Runtime

instance writes stdout and stderr messages. If you do not set this environment variable explicitly, the tc Runtime instance writes stdout and stderr messages to the file CATALINA_BASE/logs/ catalina.out.

For example, to specify that the tc Runtime instance write its stdout and stderr messages to /opt/ pivotal/tcserver/tcruntime-instance-6.log, set the variable in your environment or setenv.sh as follows:

(25)

• INSTANCE_NAME . Name of the tc Runtime instance. You can use this variable to create other unique

variables within configuration scripts.

For example, on Unix platforms you can update the bin/setenv.sh file to use the name of the tc Runtime instance when defining the CATALINA_OPTS variable as follows:

CATALINA_OPTS="-Dinstance.name=$INSTANCE_NAME"

On Windows, the equivalent change would be to the conf/wrapper.conf file as follows: set CATALINA_OPTS=-Dinstance.name=%INSTANCE_NAME%

• INSTANCE_BASE . Specifies the parent directory of the tc Runtime instance. The full pathname of the tc

Runtime instance directory would be $INSTANCE_BASE/$INSTANCE_NAME.

You can use the INSTANCE_BASE variable in the same way as the INSTANCE_NAME variable, as described in the preceding bullet.

tc Runtime Instance Directory Structure

After you create a new tc Runtime instance, its CATALINA_BASE directory contains the following subdirectories:

• bin . Contains the tcruntime-ctl.* scripts to start and stop tc Runtime instances, as well as the setenv.* scripts. The *.sh Unix files are functional duplicates of the *.bat Windows files. • conf . Contains the configuration files for the tc Runtime instance, such as server.xml,

catalina.properties, web.xml, context.xml, and so on.

• lib . Contains resources shared by all Web applications deployed to the tc Runtime instance.

• logs . Location of the logs files.

• webapps . Deployment directory for the Web applications deployed to the tc Runtime instance.

• work . Temporary work directory for all deployed Web applications.

• temp . Directory used by the JVM for temporary files.

tc Runtime Instance Configuration Files

You configure a particular tc Runtime instance by changing its configuration files. Other topics in this documentation describe how to do this. All the configuration files for a tc Runtime instance are located in its CATALINA_BASE/conf directory. The most important configuration files are as follows:

• server.xml . Main configuration file for a tc Runtime instance. It configures the behavior of the

servlet/JSP container.

By default, the server.xml file for a tc Runtime instance uses variable substitution for configuration properties that must be unique across multiple tc Runtime instances on the computer, such as HTTP and JMX port numbers. These variables take the form ${var}. For example, the variable for the HTTP port that the tc Runtime instance listens to is ${http.port}. The specific values for these variables for a particular tc Runtime instance are stored in the catalina.properties file, in the same directory as the server.xml file.

• catalina.properties . Properties file that contains the tc Runtime instance-specific values for

variables in the server.xml file.

• context.xml . Configures the context that is loaded by all Web applications deployed to the tc

Runtime instance.

• web.xml . Default web.xml file that is loaded by all deployed Web applications, in addition to their individual web.xml files.

• wrapper.conf . Windows only. Configures the Java Service Wrapper from Tanuki Software used to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user log outs under Windows, service dependencies, and the ability to run services that interact with the desktop. • jmxremote.access and jmxremote.password . Configures the JMX users and passwords. The

default JMX user, added at instance creation time unless you specify something different, is called admin with a password made up of a list of random characters.

(26)

• logging.properties . Configures the logging system of the tc Runtime instance.

Enabling Bash Completion for tc Server Scripts

If you use the bash shell on a Unix-like system and you have the bash-completion package installed, you can enable completion support for the tc Server tcruntime-instance.sh and tcruntime-ctl.sh scripts. When enabled, you can press the Tab key after entering a few letters of a command argument and either the argument is completed for you or possible alternatives are suggested. Bash completion is enabled by linking the bash completion scripts supplied with tc Server into the bash_completion.d directory on your system.

Prerequisites

• You must be using the bash shell on a Unix-like system and have the bash-completion package installed and enabled.

• Know the location of the bash_completion.d directory on your system, usually /etc/ bash_completion.d.

• You need superuser access to install the scripts. Either log in as root, or use su or sudo to temporarily become root.

Procedure

1. As the superuser, create symbolic links for the tc Server bash completion scripts in the

bash_completion.d directory, using a command like the following: prompt# ln -s

/opt/pivotal/tcserver/pivotal-tc-server-standard-3.0.2.RELEASE/bash_completion/* /etc/bash_completion.d

Replace /etc/bash_completion.d with the path to the bash_completion.d directory on your system, if it differs.

2. With your regular user login, start a new bash shell or re-source your environment to allow the bash_completion script to recognize the new tc Server scripts.

Setting Up Unix Users for tc Server and VMware vCenter Hyperic

On Unix-like systems, the interaction between VMware vCenter Hyperic and tc Server is straightforward as long as tc Runtime instances and the Hyperic Agent run as the same user.

You can run Hyperic Agent and tc Runtime instances with different user IDs. You might do this for

increased security, or because the Hyperic Agent needs to run as a privileged user to manage some other resource on the computer, or perhaps you want to run different tc Runtime instances as different users to take advantage of process accounting.

The Hyperic tc Server plug-in detects the user and group running the tc Server process and records them in parameters in the Hyperic Server resource created for the instance. If the user is different from the user running Hyperic Agent, the plug-in uses su or sudo to set the user whenever you start, restart, or stop a tc Runtime instance or change the tc Runtime instance's configuration through Hyperic.

Both Hyperic Agent and tc Runtime instances should run as regular, non-root users. Never run a tc Server instance as root.

If you use different non-root users to run tc Server instances and Hyperic Agent, you must create them in the same primary group. This is necessary to allow Hyperic Agent to read files written by the tc Runtime instance.

Subtopics

(27)

Setting the tc Server User in Hyperic

Enabling Hyperic Agent Access to su or sudo

Creating Users and Groups for Hyperic Agent and tc Server

When you run Hyperic Agent and tc Runtime instances with different users, they must be in the same primary group to allow them to share files. For better security, you can create a separate group for them. The following procedure shows how to create a group and add users to it for tc Server and Hyperic Agent on Red Hat Linux. The exact commands may be different on other operating systems.

Procedure

1. Log in as root and start a terminal session.

2. Use the groupadd command to create a new group. The following example creates a pivotal group: prompt$ groupadd pivotal

Note that if you installed from RPM on RHEL or from a Debian package on Ubuntu, the pivotal group may already exist.

3. Use the useradd command to create a user for Hyperic Agent in the group you created in the previous step. The following example creates a hyperic user in the pivotal group:

prompt$ useradd hyperic -g pivotal

You can include the -M option to prevent creating a home directory for the user and the -s /sbin/ nologin option to prevent anyone from logging in as the hyperic user.

Install and run Hyperic Agent as this user.

4. Use the useradd command to create a user to run tc Server instances. The following example creates a tcserver user in the pivotal group:

prompt$ useradd tcserver -g pivotal

You can include the -M option to prevent creating a home directory for the user and the -s /sbin/ nologin option to prevent anyone from logging in as the tcserver user.

Create the tc Server instance and run it as this user.

5. If you want to run multiple tc Runtime instances under separate user accounts on the same computer,

repeat the previous step to create additional tc Server users.

Setting the tc Server User in Hyperic

Hyperic uses auto-discovery to detect tc Runtime instances. The first time it discovers an instance, it records the user and group running the process. Therefore, the usual method to set the tc Server user is to create the instance and run it as the desired user, allowing Hyperic Agent to discover the instance.

If you are migrating to a new Hyperic release and you have existing tc Runtime instances detected by an earlier version of Hyperic, the user and group parameters are blank. The first time auto-discovery runs, the instances will show up as modified in the auto-discovery queue. When you accept the modified resources, the user and group are recorded.

If you decide to change the tc Server user for an instance previously created with a different user, be sure to chown all the files in the tc Runtime instance directory and ensure they are readable and writable by the new user. Then start the instance as the new user and trigger auto-detect in Hyperic to record the new user in the Hyperic resource record.

Enabling Hyperic Agent Access to su or sudo

Hyperic Agent uses the su or sudo command to execute tasks as the tc Server user. Specifically, if Hyperic Agent is running as root, it uses /bin/su to change to the desired user to perform the task. If

(28)

running as a non-root user, Hyperic Agent instead uses /bin/sudo to do the work as the tc Server user. There are some prerequisites you must verify to ensure that Hyperic can use su or sudo, described below.

If Hyperic Agent is running as root

If Hyperic Agent is running as root, it will use su to execute tasks as the tc Server user. You must ensure that /bin/su exists. If not, create a link to it.

For example, if su is in /sbin, but not /bin, create a link as follows: prompt$ sudo ln -s /sbin/su /bin/su

If Hyperic Agent is running as a non-root user

If Hyperic Agent is running as a non-root user, it will use sudo to execute tasks as the tc Server user. You must ensure that /usr/bin/sudo exists and also grant required permissions to the tc Server user in the /etc/sudoers file.

For example, if sudo is in /usr/sbin/, but not /bin, create a link as follows: prompt$ sudo ln -s /usr/sbin/sudo /bin/sudo

The user running Hyperic Agent needs permission to run the tcruntime-ctl.sh script as the tc Server user without having to enter a password. This is accomplished by editing the /etc/sudoers file as root and adding an entry. For example, if Hyperic Agent is running as user hyperic, tc Server runtime instances are running as user tcserver, and the tcruntime-ctl.sh script is in /opt/pivotal/ pivotal-tc-server-standard-3.0.2.RELEASE/tcruntime-ctl.sh, you would add the following entry to /etc/sudoers:

hyperic ALL=(tcserver) NOPASSWD: /opt/pivotal/pivotal-tc-server-standard-3.0.2.RELEASE/tcruntime-ctl.sh

Uninstalling tc Server: Typical Steps

You can uninstall one or more of the following components: • tc Runtime

Uninstallation of tc Server mostly entails removing the directories that contain the component files, although a few extra steps might be required, as described below.

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

Warning: The procedures in this section describe how to completely remove the components of tc

Server from your computer.

Uninstalling Hyperic Agent

To uninstall the Hyperic Agent component of tc Server:

1. If the agent itself is managed by Hyperic, remove the platform for the agent using the Hyperic user

interface.

2. Start a terminal window (Unix) or Command Prompt (Windows).

3. Remove the directory in which you installed the Hyperic Agent. For example:

prompt$ cd /opt/vmware/hyperic prompt$ rm -rf <version>

Uninstalling tc Runtime

(29)

1. If currently running, stop all tc Runtime instances. See Starting and Stopping tc Runtime Instances.

2. Start a terminal window (Unix) or Command Prompt (Windows).

3. Windows only. If you installed any tc Runtime instances as Windows services, change to the

CATALINA_BASE\bin directory of each instance (such as \var\opt\pivotal\pivotal-tc-server-standard\myserver\bin) and uninstall the service using the following command: prompt> \var\opt\pivotal\pivotal-tc-server-standard\myserver\bin prompt> tcruntime-ctl.bat uninstall

4. Remove the main tc Server installation directory. For example, if you installed Standard Edition, the

delete command might look something like the following:

prompt$ rm -rf /opt/pivotal/pivotal-tc-server-standard

By default, the home directory of all tc Runtime instances is under the main tc Server installation directory; if you used this default location when you created the tc Runtime instances with the tcruntime-instance script, then the preceding delete command also deleted all tc Runtime instances.

5. If you created any tc Runtime instances in locations other than the default tc Server installation

directory, remove their corresponding home directories.

Creating and Managing tc Runtime Instances

After you install Pivotal tc Server components on all relevant computers, you perform some or all of the following post-installation tasks, depending on the edition of tc Server. (As a performance-monitoring alternative to VMware vCenter Hyperic, you can install and configure Spring Insight. See the Spring Insight Operations documentation.)

Subtopics

Create and Modify a tc Runtime Instance Manually Windows: Create and Modify tc Runtime Instances Start and Stop tc Runtime Instances Manually Deploy Applications to tc Runtime Instances Embed 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: • Create tc Runtime Instances with the tcruntime-instance Command Script

• tcruntime-instance.sh Reference

• Create Evaluation Instances with the createInstance Script

• Pin tc Runtime Instances to a Specific Version

• Best Practice: Naming tc Runtime Instances

• Differences Between the Separate and Combined Layouts

• Using the tc Runtime Templates

• Templates Provided by tc Runtime

• Additional Information About Using the SSL Templates

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

(30)

Creating tc Runtime Instances with the tcruntime-instance Command

Script

This section describes the simplest way to use the tcruntime-instance 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 INSTALL_DIR/pivotal-tc-server-edition -release directory, where

INSTALL_DIR refers to the main tc Server installation directory, such as /opt/pivotal, edition refers to the edition of tc Server you are using (developer or standard.), and release is the release specifier For example:

prompt$ cd /opt/pivotal/pivotal-tc-server-standard-2.9.0.RELEASE

5. Run the tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) script, passing it the create serverName option. Replace serverName with the name of your new tc Runtime instance. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.

Pivotal recommends that you use the -i option to specify the full pathname of a directory in which the new instance will be created, and that this directory be different from the installation directory. Be sure the appropriate user (such as tcserver) can write to this directory and that the directory already exists.

For example, on Unix:

prompt$ ./tcruntime-instance.sh create -i /var/opt/pivotal/pivotal-tc-server-standard myserver

On Windows:

prompt> tcruntime-instance.bat create -i \var\opt\pivotal\pivotal-tc-server-standard myserver

When the preceding sample command completes, the new tc Runtime instance is located in the /var/ opt/pivotal/pivotal-tc-server-standard/myserver 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 are the default values:

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

The preceding tcruntime-instance sample did not specify the --version option, so the instance is pinned to the highest tc Runtime version located in the installation directory, 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 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, you can use the --property option to specify the Unix runtime user for the tc Runtime instance.

Product Documentation. Pivotal tc Server. Version 3.x. Getting Started with Pivotal tc Server. Rev: Pivotal Software, Inc.

Pivotal

™

tc Server

®

Version 3.x

Getting Started with Pivotal tc Server

Rev: 03

Notice

Copyright

Contents

Preface: Contacting Pivotal...vi

Chapter 1: About Getting Started with Pivotal tc Server...8

Contacting Pivotal

Current Pivotal Customers

Public Inquiries About Application Fabric Products

Chapter

1

About Getting Started with Pivotal tc Server

Intended Audience

Quick Start

Overview of tc Server

Usability Enhancements to Apache Tomcat

Easy Monitoring with the VMware vCenter Hyperic Agent Plug-In

Agile Application Development with Spring Insight Developer

Application Cluster Monitoring with Spring Insight Operations

tc Server Editions

Developer Edition

Standard Edition

Spring Edition

Migrating Java EE Applications to tc Server

Related Documentation

Installing Pivotal tc Server

Install tc Server Standard Edition From a ZIP or TAR File

Mac OS X: Install Pivotal tc Server Developer Edition as a

Homebrew Brew

Install Pivotal tc Server Developer Edition

RHEL: Install Pivotal tc Server Standard Edition from an RPM

Install Pivotal tc Server from the Pivotal RPM Repository

Install Pivotal tc Server From a Downloaded RPM

Ubuntu: Install Pivotal tc Server from the Pivotal Debian Package

Repository

Windows: Install tc Server Standard or Developer Edition Using

the MSI Installer

Install Hyperic Agent Plugin

Install tc Server Developer Edition From a ZIP or TAR File

Overview of tc Server Directories, Variables, and Configuration

Files

tc Server Variables

tc Runtime Instance Directory Structure

tc Runtime Instance Configuration Files

Enabling Bash Completion for tc Server Scripts

Setting Up Unix Users for tc Server and VMware vCenter Hyperic

Creating Users and Groups for Hyperic Agent and tc Server

Setting the tc Server User in Hyperic

Enabling Hyperic Agent Access to su or sudo

Uninstalling tc Server: Typical Steps

Uninstalling Hyperic Agent

Uninstalling tc Runtime

Creating and Managing tc Runtime Instances

Create and Modify a tc Runtime Instance Manually

Creating tc Runtime Instances with the tcruntime-instance Command

Script