Configure the Stages server
Stages installation location
The Stages installation location is referenced in this document as <STAGES_HOME>
or $STAGES_ROOT
which is the environment variable used by Stages to determine its base directory. The default location for $STAGES_ROOT
is:
Windows:
C:\methodpark\stages\
Linux:
/opt/stages/
Stages file structure
In the $STAGES_ROOT
directory you will find the following subdirectories:
Directory | Usage | customizations possible |
---|---|---|
bin | Commandline tools | ✘1) |
cmd-lib | Libraries for commandline tools | ✘ |
conf | Configuration files directory referenced as $STAGES_CONF | ✔ |
data-cache | Preprocessed configuration files and file cache for CMS data | ✘2) |
elasticsearch | Local Elastic search server used for Stages full text search feature | ✘ |
lib | Customer specific libraries, i.e. JDBC database driver and custom integrations. Directory is referenced as $STAGES_LIB | ✔ |
local | internal use | ✔ |
logs | Stages log files for error analysis. Directory is referenced as $STAGES_LOGS | ✔ |
tomcat | Tomcat application server with Stages application | ✘ |
Important configuration files
File | Usage | Shareable |
---|---|---|
Global | ||
$STAGES_ROOT/config.bat (Windows) $STAGES_ROOT/bin/rc.conf (Linux) | Configuration of Stages Service Parameters | ✔ |
Basic configuration | ||
$STAGES_CONF/server.xml | Configuration of HTTP ports and certificates | ✔3) |
$STAGES_CONF/config.xml | Stages configuration | ✔4) |
$STAGES_CONF/database.properties | Stages database connection configuration for MySQL or OracleDB | ✔5) |
$STAGES_CONF/config.properties | Properties used for variable replacement | ✘6) |
$STAGES_CONF/secret.properties | Properties used for variable replacement of passwords and other secrets | ✘7) |
$STAGES_CONF/rewrite-customer.config | Custom URL rewriting | ✘ |
$STAGES_CONF/log4j-customer.xml | Customisation of logging | ✘ |
Stages license files | ||
$STAGES_CONF/license.xml | ✘ | |
$STAGES_CONF/signature.xml | ✘ | |
$STAGES_CONF/licences | ✘ | |
Certificates | ||
$STAGES_CONF/*.crt $STAGES_CONF/*.p12 $STAGES_CONF/*.jks | ✘ | |
Kerberos SSO | ||
$STAGES_CONF/jaas.conf | ✘ | |
$STAGES_CONF/*.keytab | ✘ | |
$STAGES_CONF/krb5.conf | ✔ | |
Metamodels and customisations | ||
$STAGES_CONF/model | Metamodels | ✔ |
$STAGES_CONF/local*.properties | Custom message properties | ✔ |
$STAGES_CONF/fonts | Custom fonts for PDF printing and visualizations | ✔ |
Shareable files can be shared between a test and a production server without modifications, as long as you stick to our configuration best practices.
Apply configuration changes
For the configuration changes to take effect you need to run the following commands which will also restart Stages, so plan for a short downtime:
Windows:
net stop stages $STAGES_ROOT\bin\update.bat net start stages
Linux:
stages reload
Best practice for managing configurations
Especially for administration of multiple Stages servers - i.e. for test and production - it is important to keep the configurations in sync to ensure results from one server are reproducible on the other server.
We therefore strongly recommend to use the variable replacement feature to extract all server specific configuration values into the config.properties and secret.properties files.
Variable replacement
- requires Stages 7.9.14.0
or newer -
This allows to keep the critical configuration files server.xml
, config.xml
and database.properties
server independent and therefore shareable, while e.g. environment specific server names and passwords are managed in the server specific config.properties and secret.properties files.
A property in config.properties or secret.properties in the format
key = value
. E.g.
general.external.hostname = stages.example.com
The property can be used as a variable in server.xml
, config.xml
and database.properties
in the format ${key}
and that will be replaced by the corresponding value. E.g. in config.xml
<notification> <serverurl>https://${general.external.hostname}/stages</serverurl> [...] </notification>
In case the same property is defined in config.properties
and secret.properties
, secret.properties
value is prefered.
General Configuration of Stages
Configuration File
Stages can be configured in the $STAGES_CONF/conf/config.xml
configuration file. In its properties section some parameters can be configured by introducing name-value pairs. For information about existing configuration parameters and their effect please contact the Stages support.
The following code configures a value of “value.of.property” for the configuration property “name.of.property”:
<properties> <property name="name.of.property" value="value.of.property"/> </properties>
Please read also Best practice for managing configurations
Configuration of Stages Service Parameters
For configuring Stages service please proceed as follows. In this example the max heap memory is changed.
- Windows:
- Open file “$STAGES_ROOT\config.bat”
- Modify the setting: set TOMCAT_OPTS=–JvmMx=<RAM in MB>
- Open a cmd with administrative permissions and navigate to folder “$STAGES_ROOT\stages\bin”
- Reinstall the Stages service: reinstallService.bat
- Restart Stages service: net start stages
- Linux:
- Open file “$STAGES_ROOT/bin/rc.conf”
- Modify the value: CONF_TOMCAT_OPTS=“-Xmx<RAM in MB>m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow”
- Restart the Stages service: stages restart
You can configure additional Java start parameter for Stages that are listed below:
- -Xmx (Max memory pool): 4048 MB
- -Xms (Initial memory pool): 4048 MB
Java Garbage Collection Strategies
The JavaVM provides a variety of different garbage collection strategies (algorithms). These different algorithms can have a huge impact on the performance of Java applications. Our internal tests have shown that for most customer scenarios the default garbage collector gives the best results. Therefore we advice our customers to leave the garbage collector settings for Stages unchanged.
Configuring the TCP Ports
Stages comes with HTTPS configured by default. The server.xml for new installations looks as follows: default server.xml
Stages is started on TCP/IP port 80, 443 and 8085 and enforces usage of HTTPS by default. Thus, it can be accessed via the URL https://<servername>. To use a different port or delegate HTTPS termination to a reverse proxy like Apache HTTP server or Nginx, change the respective lines in the Tomcat configuration file named $STAGES_CONF/server.xml
.
When you try to access Stages via HTTP the client will be redirect to HTTPS instead.
To change the HTTPS port, change the port number within the following statement:
<Connector port="443" protocol="org.apache.coyote.http11.Http11Nio2Protocol" URIEncoding="UTF-8" maxHttpHeaderSize="8192" maxThreads="500" minSpareThreads="50" enableLookups="false" [...] </Connector>
For example, to use HTTPS on port 8443, comment out the statement above and enable the statement below:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11Nio2Protocol" URIEncoding="UTF-8" maxHttpHeaderSize="8192" maxThreads="500" minSpareThreads="50" enableLookups="false" [...] </Connector>
Port 8085 for internal communication
Please ensure the connector for port 8085 is always available, as it will be used for internal communication of Stages to deliver the reports and PDF print features. In the default configuration port 8085 is not reachable from other machines.
<Connector port="8085" protocol="org.apache.coyote.http11.Http11Nio2Protocol" proxyName="${general.external.hostname}" proxyPort="443" secure="true" scheme="https" URIEncoding="UTF-8" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" enableLookups="true" acceptCount="100" connectionTimeout="60000" disableUploadTimeout="true" address="127.0.0.1" />
Please configure the Stages hostname as it is used by the end users in $STAGES_CONF/config.properties
as general.external.hostname
, e.g.
general.external.hostname = stages.example.com
In case you use a IPv6 only configuration please replace address=“127.0.0.1”
by address=“::1”
Further explanations of the connector attributes are available at https://tomcat.apache.org/tomcat-9.0-doc/config/http.html
Configuring TLS/SSL Certificate
Stages comes with a self signed certificate for https://stages.localhost. Of course this needs to be replaced by your own certificate for production use.
- Register a DNS alias for the server, e.g. “stages.company.com”
- Apply for a TLS/SSL certificate for the server which refers to the above alias. Depending on your local procedures, this might require creating a certificate request (e.g. see https://www.digicert.com/kb/csr-ssl-installation/tomcat-keytool.htm for more info).
- Store your PKCS#12 (requires JDK 8u301 or newer) or JKS keystore file in
$STAGES_CONF
directory and adapt the following configuration properties accordingly:
$STAGES_CONF/stages.properties
general.external.hostname = stages.example.com general.keystore.path = conf/stages-self-signed-keystore.p12
$STAGES_CONF/secret.properties
general.keystore.keyAlias = stages general.keystore.password = SECRET
Configuration for usage with Reverse Proxy
in case you want to terminate the TSL connection on a reverse proxy (https://en.wikipedia.org/wiki/TLS_termination_proxy), you need to adapt the server.xml
and remove the default connectors for port 80 and 443. Instead you need to add a connector for the reverse proxy connection, either an AJP connector or an HTTP connector. Please refer to https://tomcat.apache.org/tomcat-9.0-doc/config/ajp.html and https://tomcat.apache.org/tomcat-9.0-doc/proxy-howto.html and your proxy documentation for details. The connector on port 8085 is always needed for internal communication.
E.g.
<Connector port="8081" protocol="org.apache.coyote.http11.Http11Nio2Protocol" URIEncoding="UTF-8" maxHttpHeaderSize="8192" maxThreads="500" minSpareThreads="50" enableLookups="false" acceptCount="1000" connectionTimeout="60000" disableUploadTimeout="true" compression="on" compressibleMimeType="text/html,text/xml,text/css,text/javascript,text/plain,application/javascript,application/json,application/xml,image/svg+xml,application/x-font-ttf" scheme="https" secure="true" proxyName="${general.external.hostname}" proxyPort="443" address="127.0.0.1" > </Connector>
or for AJP
<Connector protocol="AJP/1.3" port="8009" secure="true" secretRequired="false" address="127.0.0.1" />
In case the reverse proxy runs on a separate machine replace the address attribute by address=“0.0.0.0”
or address=“::”
and additionally apply IP filters on operation system level to ensure the port is only reachable from the reverse proxy.
Please also make sure websocket connections (ws:
) are forwarded by your reverse proxy.
Here is an example for Apache HTTP server configuration using an HTTP connector for Stages on port 8081:
<VirtualHost *:443> ServerName {{ general_external_hostname }} Redirect permanent / https://{{ general_external_hostname }}/stages ProxyPass /stages/socket ws://{{ internal_hostname }}:8081/stages/socket ProxyPassReverse /stages/socket ws://{{ internal_hostname }}:8081/stages/socket ProxyPass /stages http://{{ internal_hostname }}:8081/stages ProxyPass /reporting http://{{ internal_hostname }}:8081/reporting ProxyPass /stages-processor http://{{ internal_hostname }}:8081/stages-processor SSLEngine on [...] </VirtualHost> <VirtualHost *:80> ServerName {{ general_external_hostname }} Redirect permanent / https://{{ general_external_hostname }} [...] </VirtualHost>
Use the system trust store
Stages should trust the certificates and CAs in the systems trust store, to be able to access Cloud Services like Sharepoint Online and other systems in a secure manner.
Windows:
Please ensure the following properties are configured in $STAGES_ROOT\config.bat
set JAVA_OPTS=[...] -Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL
This is the default for new installations of Stages 7.9.14.0 or newer.
Linux:
Please ensure to use the proper update-ca-trust
or respective script of your distribution, that should ensure to copy the certificates to the system and the JAVA truststore.
Licenses
Stages is delivered with a temporary license that allows running Stages on any machine. Running Stages with a permanent license requires the Stages server machine to have a fixed IP address. To request a permanent license for running Stages on a specific server, please follow these steps:
- Install Stages on the server
- Log in as root or equivalent admin permissions
- Go to the Administration menu
- Click on “Request a License” in the “Further Information” section
- An email with all the necessary information will be opening
- Send the email to the Stages Customer Care team
Local Message Customization
The messages shown on the Stages Graphical User Interface (GUI) can be customized to the terminology used within an organization. This also applies to the textual representations for the configured news application categories.
Each message possesses a standard definition which can be overwritten by local definitions. These local messages can be configured in the file $STAGES_CONF/local.properties
and its localized versions (e.g. $STAGES_CONF/local_de.properties
). At system startup, your messages will be automatically merged into the message pool of Stages.
The format of the message files conforms to the Java property files standard (“name = value”).
CMS Configuration
Stages can interact with configuration management systems to work with remotely stored files. Please find the details of the configuration here.
CMS Prefetch configuration
Please find the details here.
Document Lifecycles
Please find the details here
Email Notifications
Please find the details here.
LDAP Synchronization
Please find the details here.