Deploy Server On-Premise with Tomcat
  • 18 Feb 2021
  • 4 Minutes To Read
  • Print
  • Share
  • Dark
    Light

Deploy Server On-Premise with Tomcat

  • Print
  • Share
  • Dark
    Light

Overview

This guide will demonstrate how to deploy the SecureCircle server software on platforms supported by Apache Tomcat.

Prerequisites

The system should have the following software available:

Installation

Java configuration

If using Java runtime environment (JRE)

Ensure the JRE_HOME environment variable is set on the system. This is generally done by the Java installer or distribution package.

On Windows the variable can be checked with the command echo %JRE_HOME%. On *nix systems it can be checked with the command echo $JRE_HOME.

If using Java development kit (JDK)

Ensure the JAVA_HOME environment variable is set on the system. This is generally done by the Java installer or distribution package.

On Windows the variable can be checked with the command echo %JAVA_HOME%. On *nix systems it can be checked with the command echo $JAVA_HOME.

Installing Tomcat

From the Tomcat 8 Software Downloads page download the zip or tar.gz (for *nix), or the 64-bit Windows zip distribution. It should be named apache-tomcat-[version].zip or .tar.gz (for *nix), or apache-tomcat-[version]-windows-x64.zip (for Windows).

Extract this base distribution of Tomcat to a location on the local filesystem. Make note of this location, as it will be set as the CATALINA_HOME environment variable.

Installing the SecureCircle server

From the Server Downloads article download the appropriate reference Tomcat configuration bundle.

Extract this bundle to a location on the local filesystem. Make note of this location, as it will be used as the CATALINA_BASE environment variable.

Information

SecureCircle Configuration

Application Configuration

The SecureCircle server software is distributed as a set of Java web applications. These applications are known as API (api.war), Router (web.war), Tracker (tracker.war), and Shrecker (shrecker.war).

These applications can be configured either via environment variables, or Java properties. The reference Tomcat configuration bundle uses Java properties for configuration, located in the CATALINA_BASE/conf/properties folder. The .properties files within this folder will need to be modified for use in your environment.

A full list of properties available for configuring the SecureCircle server can be found in the Deploy SecureCircle server on-premises article.

Additional environment variables (LOG_FILE_APPENDER_PATH, LOG_FILE_APPENDER_LEVEL, and CONSOLE_APPENDER_LEVEL) are used for log configuration, these cannot be configured by Java properties. These can be modified in setenv.bat or setenv.sh located in CATALINA_BASE/bin.

Information

If Tomcat will be running as a Windows service, these APPENDER variables will need to be set manually. The setenv files are only used with the catalina script.

Additional Applications

  • The ROOT application provides URL rewrite rules.
  • The download application provides agent downloads from the server.
  • The images application provides image assets used in emails.
  • The shrecker-static application provides UI assets for the Shrecker application.
  • The web-static application provides UI assets for the API application.

TLS/SSL Configuration

An HTTPS listener is configured by default in CATALINA_BASE/conf/server.xml. A PKCS12 (PFX) formatted keychain with the password changeit is expected in CATALINA_BASE/conf/keychain.pfx.

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keystoreFile="conf/keychain.pfx"
               keystoreType="PKCS12"
               keystorePass="changeit" />

Alternative keychain formats can be configured. See Tomcat's SSL/TLS Configuration HOW-TO and HTTP Connector pages for more information.

Information

The Windows-My or Windows-ROOT keystoreType can be used if the keychain is in the Windows certificate store.
https://tomcat.apache.org/tomcat-8.5-doc/config/http.html#Key_store_types
https://bz.apache.org/bugzilla/show_bug.cgi?id=56021#c3

Running the Server

For more information please refer to the Tomcat Setup page.

Manual

Assuming the CATALINA_HOME and CATALINA_BASE environment variables have been set, the Tomcat server can be started with the catalina.bat or catalina.sh script located in CATALINA_BASE/bin.

The start argument can be used to run Tomcat in the background, or the run argument to run in the foreground.

*nix Systems

export CATALINA_HOME=/opt/tomcat8
export CATALINA_BASE=/opt/securecircle
$CATALINA_BASE/bin/catalina.sh start

Windows Systems

set CATALINA_HOME=C:\tomcat8
set CATALINA_BASE=C:\securecircle
%CATALINA_BASE%\bin\catalina.bat start

Installation as a Windows Service

For more information please refer to the Tomcat Windows service HOW-TO page.

Install the Service

The environment variable LOG_FILE_APPENDER_PATH should be set to the full path of CATALINA_BASE\logs for the user running the Tomcat server. The default value will write logs to C:\var\log\securecircle. Be sure to replace CATALINA_BASE with the full path.

set CATALINA_BASE=c:\securecircle
set LOG_FILE_APPENDER_PATH=%CATALINA_BASE%\logs

Assuming the CATALINA_HOME and CATALINA_BASE environment variables have been set, the Tomcat server can be installed as a service with the service.bat script located in CATALINA_HOME\bin.

set CATALINA_HOME=c:\tomcat8
set CATALINA_BASE=c:\securecircle
%CATALINA_HOME%\bin\service.bat install SecureCircle

This will install a manageable service:
tomcat.png

Modify the Service

The service can be modified by running the command:

%CATALINA_HOME%\bin\tomcat8w.exe //ES//SecureCircle

The -Djava.util.logging.config.file line needs to be removed. It is not provided in CATALINA_BASE.

The Maximum memory pool size needs to be increased. This is the -Xmx (maximum heap size), and should be set to a minimum of 512MB. It generally defaults to 50-75% of system memory up to 1-2gb.
https://docs.oracle.com/cd/E13150_01/jrockit_jvm/jrockit/jrdocs/refman/optionX.html#wp999528

tomcat2.png

If Tomcat will be running under an account other than the Local System account, that account must be granted the right to Log on as a service.

tomcat3.png

tomcat4.png

Manage the Service

A system tray icon, allowing service configuration and management, can be enabled by running the command:

%CATALINA_HOME%\bin\tomcat8w.exe //MS//SecureCircle

tomcat5.png

Was This Article Helpful?