- 05 Oct 2021
- 4 Minutes to read
-
Print
-
DarkLight
-
PDF
Deploy Server On-Premise with Tomcat
- Updated on 05 Oct 2021
- 4 Minutes to read
-
Print
-
DarkLight
-
PDF
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
- 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.
- Server Downloads article
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.
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.
A self-signed certificate can be generated with the keytool
command like:
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.
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:
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