Configure the Stages server

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/

In the $STAGES_ROOT directory you will find the following subdirectories:

Shareable files can be shared between a test and a production server without modifications, as long as you stick to our configuration best practices.

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

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.

- requires Stages 7.10.5.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.

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

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

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.

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>

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

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

Apply the configuration changes

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

SSLEngine on
[...]
</VirtualHost>

<VirtualHost *:80>
ServerName {{ general_external_hostname }}

Redirect permanent / https://{{ general_external_hostname }}

[...]
</VirtualHost>

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

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

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

Stages can interact with configuration management systems to work with remotely stored files. Please find the details of the configuration here.

Please find the details here.

Please find the details here

Please find the details here.

Please find the details here.