Differences

This shows you the differences between two versions of the page.

--- 710:configure_stages [2024/03/08 10:13] – Weinlein, Thomas
+++ 710:configure_stages [2024/10/30 11:27] (current) – [Configuring TLS/SSL Certificate] Weinlein, Thomas
@@ Line 1: / Line 1: @@
-====== Configure the Stages server (under rework) ======
+====== Configure the Stages server ======
-* [[:710:customization_of_stages|]]
+===== Stages installation location =====
-  * [[:710:general_configuration|]]
+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:
-  * [[:710:java_garbage|Java Garbage Collection Selection]]
-  * [[:710:local_message_custom|]]
-  * [[:710:local_style_custom|]]
-  * [[:710:cms_configuration|]]
-  * [[:710:cms_prefetch|]]
-  * [[:710:network_config|]]
-  * [[:710:database_config|]]
-  * [[:710:email_notification|Email Notification]]
-  * [[:710:email_authentication|]]
-  * [[:710:ldap|LDAP Synchronization]]
-  * [[:710:document_lifestyles|]]
-  * [[:install:fonts79|Process Visualization/PDF Font Configuration]]
-===   ===
+Windows:
+<code ->
+C:\methodpark\stages\
+</code>
+Linux:
+<code ->
+/opt/stages/
+</code>
+===== Stages file structure =====
+In the ''$STAGES_ROOT'' directory you will find the following subdirectories:
+^ Directory ^ Usage ^ customizations possible ^
+| bin | Commandline tools |  **✘**((
+with exception of rc.conf on Linux
+))  |
+| 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 |  **✘**((
+could be deleted and will be recreated automatically
+))  |
+| 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'' | [[#Configuring the TCP Ports|Configuration of HTTP ports]] and [[#configuring-tlsssl-certificate|certificates]] |  **✔**((
+by using variable replacement
+))  |
+| ''$STAGES_CONF/config.xml'' | [[#Configuration File|Stages configuration]] |  **✔**((
+by using variable replacement
+))  |
+| ''$STAGES_CONF/database.properties'' | Stages database connection configuration for [[install#Establish database connection with MySQL|MySQL]] or [[install#Establish database connection with Oracle|OracleDB]] |  **✔**((
+by using variable replacement
+))  |
+| ''$STAGES_CONF/config.properties'' | Properties used for [[#variable replacement]]  |  **✘**((
+property values are server specific
+))  |
+| ''$STAGES_CONF/secret.properties'' | Properties used for [[#variable replacement]] of passwords and other secrets |  **✘**((
+property values are server specific
+))  |
+| ''$STAGES_CONF/rewrite-customer.config'' | Custom URL rewriting |  **✘**  |
+| ''$STAGES_CONF/log4j-customer.xml'' | Customisation of logging |  **✘**  |
+| [[#Licenses|Stages license files]] |||
+| ''$STAGES_CONF/license.xml'' |  |  **✘**  |
+| ''$STAGES_CONF/signature.xml''  |  |  **✘**  |
+| ''$STAGES_CONF/licences'' |  |  **✘**  |
+| [[#configuring-tlsssl-certificate|Certificates]] |||
+| ''$STAGES_CONF/*.crt'' \\ ''$STAGES_CONF/*.p12'' \\ ''$STAGES_CONF/*.jks'' |  |  **✘**  |
+| [[kerberos_autologin|Kerberos SSO]] |||
+| ''$STAGES_CONF/jaas.conf'' |  |  **✘**  |
+| ''$STAGES_CONF/*.keytab'' |  |  **✘**  |
+| ''$STAGES_CONF/krb5.conf'' |   |  **✔**  |
+| Metamodels and customisations |||
+| ''$STAGES_CONF/model'' | [[install#install-customer-specific-metamodel-if-available|Metamodels]] |  **✔**  |
+| ''$STAGES_CONF/local*.properties'' | [[#Local Message Customization|Custom message properties]] |  **✔**  |
+| ''$STAGES_CONF/fonts'' | [[install/fonts79|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 [[#Best practice for managing configurations|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:**
+<code>
+net stop stages
+$STAGES_ROOT\bin\update.bat
+net start stages
+</code>
+**Linux:**
+<code>
+stages reload
+</code>
+===== 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.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
+<code properties>
+key = value
+</code>
+. E.g.
+<code properties>
+general.external.hostname = stages.example.com
+</code>
+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''
+<code xml>
+<notification>
+    <serverurl>https://${general.external.hostname}/stages</serverurl>
+    [...]
+</notification>
+</code>
+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”:
+<code xml>
+<properties>
+    <property name="name.of.property" value="value.of.property"/>
+</properties>
+</code>
+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: [[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>|https://<servername>]]. To use a different port or [[#configuration-for-usage-with-reverse-proxy|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:
+<code xml>
+<Connector
+    port="443"
+    protocol="org.apache.coyote.http11.Http11Nio2Protocol"
+    URIEncoding="UTF-8"
+    maxHttpHeaderSize="8192"
+    maxThreads="500"
+    minSpareThreads="50"
+    enableLookups="false"
+    [...]
+</Connector>
+</code>
+For example, to use HTTPS on port 8443, comment out the statement above and enable the statement below:
+<code xml>
+<Connector port="8443"
+    protocol="org.apache.coyote.http11.Http11Nio2Protocol"
+    URIEncoding="UTF-8"
+    maxHttpHeaderSize="8192"
+    maxThreads="500"
+    minSpareThreads="50"
+    enableLookups="false"
+    [...]
+</Connector>
+</code>
+=== 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.
+<code xml>
+<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"
+/>
+</code>
+Please configure the Stages hostname as it is used by the end users in ''$STAGES_CONF/config.properties'' as ''general.external.hostname'', e.g.
+<code properties>
+general.external.hostname = stages.example.com
+</code>
+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/config.properties''
+<code properties>
+general.external.hostname = stages.example.com
+general.keystore.path = conf/stages-self-signed-keystore.p12
+</code>
+''$STAGES_CONF/secret.properties''
+<code properties>
+general.keystore.keyAlias = stages
+general.keystore.password = SECRET
+</code>
+[[#apply-configuration-changes|Apply the configuration changes]]
+==== 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.
+<code xml>
+<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>
+</code>
+or for AJP
+<code xml>
+<Connector protocol="AJP/1.3"
+               port="8009"
+               secure="true"
+               secretRequired="false"
+               address="127.0.0.1"
+               />
+</code>
+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:
+<code>
+<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>
+</code>
+==== 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''
+<code>
+set JAVA_OPTS=[...] -Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL
+</code>
+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.
+===== 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 [[cms_configuration|here]].
+==== CMS Prefetch configuration ====
+Please find the details [[cms_prefetch|here]].
+==== Document Lifecycles ====
+Please find the details [[document_lifestyles|here]]
+===== Email Notifications =====
+Please find the details [[email_notification|here]].
+===== LDAP Synchronization =====
+Please find the details [[ldap|here]].