Installing tc Server: Typical Steps

This topic contains the following sections:

NOTE: It is assumed in this section that you are installing tc Server for the first time. If, however, you have already installed a previous version of tc Server and created one or more tc Server instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide for detailed information about the upgrade process.

Overview of Installation

SpringSource tc Server is distributed in three different ZIP or TAR files, each containing a different combination of components. See Installing tc Server and Creating a New Server Instance for detailed information about what each distribution contains. Note that to install just the AMS server, you must download the entire distribution.

The naming convention for these distribution files is as follows:

The installation scripts in each distribution are essentially the same; the only difference is in the components that are available for you to install.

The preceding distribution files each include an installation script (install.sh on Unix and install.bat on Windows). SpringSource also distributes the underlying Tomcat server in a file that does not contain an installation script but rather is just a self-extracting JAR bundle; this file is called tcServer-version-tomcat.sfx.jar. It is assumed in most of this section that you are installing from a file that contains an installation script; if, however, you want to simply extract the underlying Tomcat server, see Installing Tomcat Server Using the Self-Extracting JAR File for additional information.

After you have decided which tc Server components you are going to install on your computer(s), you download the appropriate distribution to that computer. As described in Installation Overview, the two typical scenarios are as follows:

The typical installation procedure describes how to interactively install tc Server for both standard scenarios. The procedure covers both Unix and Windows installation, although the instructions are for Unix. If you are installing on Windows, change the forward slashes (/) to back slashes (\); other differences in the installation are called out.

If you are installing either a managed node (AMS agent and application server) or application server only, you can also install silently by passing properties to the install.sh or install.bat script. This feature, however, is not available when installing a full distribution (AMS server, AMS agent, and application server.) For details about silent installation, see Silently Installing a Managed Node or Application Server.

Tip: The installation of the AMS components of tc Server follows the generic AMS installation procedure; for complete documentation, see the SpringSource AMS Manual.

The tc Server installer program is supported on versions 1.5 and 1.6 of the JDK.

Important Note When Installing on Unix Platforms

The tc Server installer program requires a GNU compatible tar. This means that, before installing tc Server on a Unix platform, you must ensure that the tar command on your computer is compatible with the one required by the tc Server installer program. To do this, open a terminal window and run the following command:

prompt$ tar --help

Search the help output for a -z option (which filters the output through gzip); if the tar command on your computer supports this option, then it is compatible with the one required by tc Server and you can begin the installation.

If, however, your tar command does not supports this option, then you must install GNUtar (gtar) from an external source. For example, the Web site Sunfreeware.com includes many free downloads for the Solaris platform, including GNUtar.

After you install GNUtar, you must ensure that the tc Server installer program can find the gtar executable by updating the PATH environment variable (either of the user running the tc Server installer program or the system-wide environment variable) to include the location of the gtar command. The location depends on the directory in which you installed GNUtar.

If you have installed GNUtar, then substitute the command gtar for any references to tar in the following install procedure.

Interactive Installation Procedure: Typical Steps

NOTE: It is assumed in this section that you are installing tc Server for the first time. If, however, you have already installed a previous version of tc Server and created one or more tc Server instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide for detailed information about the upgrade process.

Follow these steps to interactively install tc Server:

  1. Read Before you Begin: System Requirements to ensure that you have the correct required system configuration and software before you begin the installation.

  2. Download the appropriate tc Server distribution from the SpringSource Download Center.

  3. Unzip or untar the tc Server distribution file into a temporary directory. Be sure the owner of the temporary directory is the same as the user that unzips/untars the distribution file, or you will get an error when you run the installer program.

    On Windows, the distribution is a self-extracting JAR file that you can expand using Windows Explorer by double-clicking on it; the file unzips in the same directory in which it is located. NOTE: Internet Explorer recognizes that the downloaded distribution file is actually formatted as a ZIP file, and by default might change its file extension from .jar to .zip. This means that if you used IE to download the distribution file and its file extension changed, you might not be able to simply double-click on it to extract its contents. If this is the case, you can either use a zip extractor program, such as 7-Zip, to extract the files, or rename the file to have a .jar extension.

    On Unix, use the tar command to extract the files. For example, to untar the file in the current directory and assign the extracted files to the same group as the user executing the command:

    prompt$ tar --no-same-owner -xvzf /home/tarfiles/tcserver-6.0.20.C-GA-linux32.tgz
  4. Start a command prompt (Windows) or a terminal (Unix.)

  5. 64-bit Unix platforms only. If you are installing tc Server on a 64-bit computer, you must explicity set the JAVA_HOME environment variable to point to a 64-bit JVM or JRE. You must also ensure that your PATH environment variable includes this 64-bit JAVA_HOME/bin directory, and that it appears before any other non-64-bit JVM/JRE. This step ensures that you are able to install all available components of tc Server (application server and AMS server/agent.)

    Use the which java Unix command to ensure your PATH variable points to the 64-bit JVM/JRE:

    prompt$ which java
    /usr/java64/jdk1.6.0_11/bin/java
  6. Change to the directory in which you unzipped the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script. For example, on Unix:

    prompt$ cd /home/springsource/tcServertmp
    prompt$ ./install.sh

    The installer program performs some checks of your system then displays a menu of options. Depending on the components that are available in the distribution, as well as the components you want to install on your computer, pick one or both of the following procedures marked in bold:

    Note that you must run the install.sh script from the directory in which it lives, and not from any other directory, or you will get an error.

  7. To install one or both of the AMS components, follow these steps:

    1. Enter the indicated number for the quick install that uses default values as much as possible; otherwise, enter the indicated number for a full install in which you provide values for all properties. If this is the first time you install tc Server, SpringSource recommends you choose the quick-install option.

      The install program performs some checks of your system and then prints the AMS installation menu. See Installing HQ for details about the full install.

    2. Enter the indicated number to install only the AMS server (if available); otherwise, enter the indicated number to install only the AMS agent, or both numbers (separated by commas) to install both the AMS server and agent on this computer.

    3. Enter the full pathname of the directory in which you want to install the AMS component(s).

      Important: The specified directory must already exist; the install program does not create it for you.

      The install program creates a directory under this main AMS installation directory for each corresponding component: for example, agent-2.0.0 and/or server-2.0.0.

      If you are installing both components at once, the installer program asks you for the installation directory for each component, which means you can install them in separate locations.

    4. If you're installing AMS server, enter the fully qualified domain name of the SMTP server that AMS will use to send email messages; the default value is the domain name of the computer on which you are running the install program.

    5. (Unix only) If you are installing AMS server, the install script asks you to login to a different terminal window as the root user and run a script called tune-os.sh to set the proper shared memory settings to run the built-in database. This is a SpringSource AMS requirement. Do not close the first terminal window from which you ran the initial installer script while you perform this step. When complete, go back to the installer terminal window and press Enter to continue with the installation.

      The following information is provided for administrators who might need to know exactly what the tune-os.sh script does, especially because it must be run as the root user. The script:

      • Checks to see if the file /etc/sysctl.conf exists. If it does not exist, the script creates it and includes the following line: kernel.shmmax=2147483648.
      • If the /etc/sysctl.conf file does exist, the script checks that the kernel.shmmax value is specified in the file. If it is not specified, the script appends the value to sysctl.conf and adds it to /proc/sys/kernel/shmmax
      • If the kernel.shmmax value is already specified, the script checks to see if the shmmax value is large enough (at least 2147483648). If it is large enough, the script skips it. If the value is too small, the script backups the current sysctl.conf file, creates a new file with the kernel.shmmax size set to 2147483648, and then updates the /proc/sys/kernel/shmmax file with that value.
    6. When the installation of the AMS components is complete, you will see the message Deleting temporary JRE ...hit return.... Hit return to get back to the main tc Server installer program. (On Windows you might have to press Enter twice.)

  8. To install tc Server application server, follow these steps:

    1. Enter the indicated number to install the tc Server application server.

    2. Enter the full pathname of the directory into which you want to install the tc Server application server.

      Important: The specified directory must already exist; the install program does not create it for you.
    3. After confirming your entry, the install program installs tc Server and then returns you to the main installer menu.

  9. Enter the indicated number to exit when you have finished installing all the required components for this computer.

Silently Installing a Managed Node or Application Server

If you are installing either a managed node (AMS agent and application server) or just the application server, you can pass properties to the install.sh or install.bat script rather than run the script interactively; this is referred to as silent installation. This feature is not available when installing the full distribution (AMS server, AMS agent, and application server.)

To install silently:

  1. Download and unzip the distribution, as described in the first four steps of the typical installation procedure.

  2. Change to the directory in which you unzipped the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script, passing it the following two properties:

    • -t appserverdir: Specifies the full pathname of the directory where you want to install the tc Server application server component.
    • -a agentdir: Specifies the full pathname of the directory where you want to install the AMS agent.

For example, to install the application server in the /home/tcserverApp directory and the AMS agent in the /home/tcserverAgent directory, run the following command:

prompt$ ./install.sh -t /home/tcserverApp -a /home/tcserverAgent

Installing Tomcat Server Using the Self-Extracting JAR File

The self-extracting JAR file that contains only the base Tomcat server is called tcServer-version-tomcat.sfx.jar. This JAR file does not contain an installation script; rather, you must perform the installation yourself using the following procedure:

  1. Open a terminal (Unix) or command (Window) window and change to the directory into which you want to install Tomcat server.

  2. Unjar the self-extracting file by running the java -jar path-to-file/tcServer-version-tomcat.sfx.jar command, where path-to-file refers to the location of the JAR file and version refers to the version of tc Server, such as 6.0.20.C-GA. For example:

    prompt$ java -jar /home/downloads/tcServer-6.0.20.C-GA-tomcat.sfx.jar

    The JAR file extracts its contents into a new tcServer-6.0 sub-directory.

  3. (Unix only) Change to the tcServer-6.0 directory and change the permissions of all *.sh files to make them executable. For example, the following Unix find command searches for all files with the sh extension and sets their permissions:

    prompt$ find . -type f -name '*.sh' -exec chmod +x "{}" \;

Next Steps

See Overview of tc Server Directories, Variables, and Configuration Files for conceptual information about tc Server directories and configuration files. See Post-Installation Tasks for the list of typical post-installation procedures, such as starting the various components of tc Server and getting started with the AMS console.

Then try out the tutorials: Tutorial: Using AMS to Configure and Manage tc Server and Tutorial: Very Simple Web Application Development.