Differences

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

--- 79:configure_stages_new [2024/03/07 14:33] – [Configuring SSL Certificate] Weinlein, Thomas
+++ 79:configure_stages_new [2024/03/12 10:16] – [Configure the Stages server **Currently under rework**] Weinlein, Thomas
@@ Line 1: / Line 1: @@
-====== Configure the Stages server  **Currently under rework** ======
+====== Configure the Stages server ======
 ===== Stages installation location =====
@@ Line 75: / Line 75: @@
 **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:**
+In case of changes to the service configurations
+<code>
+$STAGES_ROOT\bin\reinstallService.bat
+</code>
+always
+<code>
+net stop stages
+$STAGES_ROOT\bin\update.bat
+net start stages
+</code>
+**Linux:**
+<code>
+stages reload
+</code>
 ===== Best practice for managing configurations =====
@@ Line 133: / Line 156: @@
   * Windows:
       * Open file "$STAGES_ROOT\config.bat"
-      * Modify the red colored setting: //set TOMCAT_OPTS=–JvmMx=<RAM in MB>//
+      * 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**
@@ Line 139: / Line 162: @@
   * Linux:
       * Open file "$STAGES_ROOT/bin/rc.conf"
-      * Modify the red colored value: //CONF_TOMCAT_OPTS="-Xmx<RAM in MB>m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow"//
+      * Modify the value: //CONF_TOMCAT_OPTS="-Xmx<RAM in MB>m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow"//
       * Restart the Stages service:** stages restart**
@@ Line 236: / Line 259: @@
 For more details on certificate generation please refer to [[certificate_generation]].
+==== Configuration for usage with Reverse Proxy ====
+in case you want to terminate the SSL connection on a reverse 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.
+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 }}
-__TODO__
+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>
-Explain proxyname proxyport secure?
+<VirtualHost *:80>
+ServerName {{ general_external_hostname }}
-Configuration with reverse proxy
+Redirect permanent / https://{{ general_external_hostname }}
-Stages comes with a self signed certificate for the domain stages.localhost and HTTPS enabled by default.  You should replace that certificate with an official one and change following properties.
+[...]
+</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 7.9.14.0 and newer.
+Linux:
-Import certificate into system truststore (windows/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.