Deploy Server On-Premise with Tomcat

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:

• 64-bit Java runtime environment (JRE) or Java development kit (JDK) 8.
  • Oracle JRE: https://www.java.com/en/download/manual.jsp
  • Oracle JDK: https://www.oracle.com/java/technologies/javase-jdk8-downloads.html
  • OpenJDK: https://adoptopenjdk.net
• Tomcat 8.5.x
  • https://tomcat.apache.org/download-80.cgi
• Reference Tomcat configuration.
  • Server Downloads article
    CPU: 2 core, 2.5GHz
    Memory: 4GB
    Disk space: 8GB
    The minimum system requirements support a peak load of 3000 requests per second, or around 20000 users. System requirements may need to be increased depending on the number of concurrent users. Doubling the server's CPU and networking resources will yield around a 1.5x performance increase.

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.

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.

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.

keytool -genkey -alias tomcat -keyalg RSA -keystore keychain.pfx -storetype PKCS12 -validity 3560 -keysize 2048

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

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:

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

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.

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