Installing Pivotal tc Server

Installation options vary according to your operating system.

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.

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

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

Procedure

  1. See Obtaining tc Server for instructions on how to download tc Server.

  2. Download the Standard Edition package distribution in ZIP or compressed TAR format then transfer to a directory on the target host, for example ~/Downloads.

  3. Log in to the computer on which you are installing tc Server as the appropriate user. On Unix, if you have disabled interactive login, login as a user with sudo privileges and use su -s /bin/sh tcserver to become the user. It is not recommended that the tcserver user have sudo privileges. On Windows, this should be a user with Administrator privileges.

  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:

    sudo mkdir -p /opt/pivotal/tcserver

    Windows example:

    mkdir \opt\pivotal\tcserver\standard

  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 tar.gz file in the user’s home directory directory:

    cd /opt/pivotal/tcserver
sudo tar xzf ~/pivotal-tc-server-standard-4.0.7.RELEASE.tar.gz

    This action creates a directory called standard-4.0.7.RELEASE in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the runtimes directory, and so on. The directory layout should look like the following

  • /opt/pivotal/tcserver/

    • standard-4.0.7.RELEASE/
    • runtimes/

    Windows (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\tcserver\standard\standard-4.0.7.RELEASE. This directory contains all the tc Runtime files and directories.

  1. Add tcserver to your PATH variable. This procedure varies based on your operating system and your own internal policies. The following are the recommended methods

    Unix: Create a file named /etc/profile.d/tcserver.sh and add the following

    export PATH=/opt/pivotal/tcserver/standard-4.0.7.RELEASE:$PATH

    Change 4.0.7.RELEASE to the version you downloaded if different.

    You’ll need to log out and back in our source that file. Example

    . /etc/profile.d/tcserver.sh

    Windows:

    1. Open Control Panel
    2. Open System
    3. Select Advanced tab
    4. Under System Variables select Path then click Edit
    5. Add \opt\pivotal\tcserver\standard\standard-4.0.7.RELEASE
    6. Click Ok
    7. Restart command prompt if open

  2. Change ownership of the files. Pivotal recommends running the tcserver command as a user dedicated to tc Server. It is necessary to give this user permissions to write to the runtimes and templates directory.

    Unix:

    chown -R tcserver:tcserver /opt/pivotal/tcserver

What to do next

Mac OS X - Install Pivotal tc Server Developer Edition Using Homebrew

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

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

RHEL - Install Pivotal tc Server Standard Edition from an RPM

Note: In previous tc Server versions RPM packages were uploaded to a YUM repository. As of tc Server 4.0, this is no longer the case. RPM packages have to be manually downloaded and installed.

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. For detailed information on obtaining tc Server please see obtaining tc Server.

Note: tc Server 4.0.x RPM obsoletes 3.x RPMs packages. Multiple versions of tc Server RPM packages may not be installed at the same time. If this is desired then tc Server must be installed via the .tar.gz package.

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.

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).
  2. See Obtaining tc Server for instructions on how to download tc Server.
  3. Download the tc Server Standard Edition RPM file to a directory on your computer. The RPM file is called pivotal-tc-server-4.0.7.RELEASE.noarch.rpm. In addition, download a tc Runtime. For new installations it is recommended to use tc Runtime 9. The tc Runtime RPM will is called pivotal-tc-runtime-9.0.6.B.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 and tc Runtime:

    rpm -Uvhf pivotal-tc-server-4.0.7.RELEASE.noarch.rpm
rpm -Uvhf pivotal-tc-runtime-9.0.6.B.RELEASE.noarch.rpm

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

    sudo rpm -Uvhf pivotal-tc-server-4.0.7.RELEASE.noarch.rpm
sudo rpm -Uvhf pivotal-tc-runtime-9.0.6.B.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.)

Install tc Server Developer Edition From a ZIP or TAR File

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

  • Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements.
  • 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.

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

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

Procedure

  1. See Obtaining tc Server for instructions on how to download tc Server.

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

  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:

    sudo mkdir -p /opt/pivotal/tcserver

  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.

  6. Add tcserver to your PATH variable. This procedure varies based on your operating system and your own internal policies. The following are the recommended methods

    Unix: Create a file named /etc/profile.d/tcserver.sh and add the following

    export PATH=/opt/pivotal/tcserver/developer-4.0.7.RELEASE:$PATH

    Change 4.0.7.RELEASE to the version you downloaded if different.

    You’ll need to log out and back in our source that file. Example

    . /etc/profile.d/tcserver.sh

    Windows:

    1. Open Control Panel
    2. Open System
    3. Select Advanced tab
    4. Under System Variables select Path then click Edit
    5. Add \opt\pivotal\tcserver\standard\developer-4.0.7.RELEASE
    6. Click Ok
    7. Restart command prompt if open

  7. Change ownership of the files. Pivotal recommends running the tcserver command as a user dedicated to tc Server. It is necessary to give this user permissions to write to the runtimes and templates directory.

    Unix:

    chown -R tcserver:tcserver /opt/pivotal/tcserver

  8. Create a tc Runtime instance.

    For example:

    tcserver create demo-instance

  9. Start the new tc Runtime instance.

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

    tcserver start demo-instance

    Windows: Execute the tcserver 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:

    tcserver install demo-instance
tcserver start demo-instance

    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.

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 <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:

  • 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 tcserver script to create a new tc Runtime instance. This is also the default location for custom template or template retrieved from the template repository. See Templates Provided by tc Runtime for the full list.
  • lib JAR files that implement the templating mechanism and are used by the tcserver script.
  • tcserver Script for provisioning, lifecycle, and administration of 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.

In addition to <edition>-<version> a runtimes directory is created which contains

  • 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-9.0.6.B.RELEASE. These directories are the basic Apache Tomcat CATALINA_HOME directory. Standard Apache Tomcat users recognize its contents. These are referred to as tc Runtimes

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/runtimes/tomcat-<version>, where INSTALL_DIR is the directory in which you installed tc Server (such as /opt/pivotal/tcserver); <version> refers to the tc Runtime (Apache Tomcat) version, such as 9.0.6.B.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/instances/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:

    CATALINA_OUT=/opt/pivotal/tcserver/tcruntime-instance-6.log

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

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

Setting Up Unix Users for tc Server

Subtopics

Creating Users and Groups for tc Server

Creating Users and Groups for tc Server

The following procedure shows how to create a group and add user to it for tc Server 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:

    groupadd pivotal

    Note that if you installed from RPM on RHEL, the pivotal group may already exist.

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

    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. If specifying /sbin/nologin as a shell to su to this user later -s /bin/bash needs to be added to the su command.

    su - tcserver -s /bin/bash

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

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

Uninstalling tc Server - Typical Steps

You can uninstall one or more of the following components:

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 tc Server

The following procedure describes how to uninstall the tc Runtime and all its associated instances.

  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. Uninstall the service using the following command:

    tcserver uninstall demo-instance

  4. Remove the main tc Server installation directory. For example, if you installed Standard Edition, the delete command might look something like the following:

    rm -rf /opt/pivotal/tcserver

  5. Remove the instances by deleting the instances directory. This will remove the instances and any web apps and configuration swell.