Stages Documentation

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Last revisionBoth sides next revision
79:configure_stages_new [2024/03/07 14:32] – [Variable replacement] Weinlein, Thomas79: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 ===== ===== 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]]. **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 ===== ===== Best practice for managing configurations =====
  
Line 118: Line 141:
 The following code configures a value of “value.of.property” for the configuration property “name.of.property”: The following code configures a value of “value.of.property” for the configuration property “name.of.property”:
  
-<code>+<code xml>
 <properties> <properties>
  <property name="name.of.property" value="value.of.property"/>  <property name="name.of.property" value="value.of.property"/>
Line 133: Line 156:
   * Windows:   * Windows:
       * Open file "$STAGES_ROOT\config.bat"       * 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"       * Open a cmd with administrative permissions and navigate to folder "$STAGES_ROOT\stages\bin"
       * Reinstall the Stages service: **reinstallService.bat**       * Reinstall the Stages service: **reinstallService.bat**
Line 139: Line 162:
   * Linux:   * Linux:
       * Open file "$STAGES_ROOT/bin/rc.conf"       * 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**       * Restart the Stages service:** stages restart**
  
Line 162: Line 185:
 To change the HTTPS port, change the port number within the following statement: To change the HTTPS port, change the port number within the following statement:
  
-<code>+<code xml>
     <Connector port="443"     <Connector port="443"
                protocol="org.apache.coyote.http11.Http11Nio2Protocol"                protocol="org.apache.coyote.http11.Http11Nio2Protocol"
Line 176: Line 199:
 For example, to use HTTPS on port 8443, comment out the statement above and enable the statement below: For example, to use HTTPS on port 8443, comment out the statement above and enable the statement below:
  
-<code>+<code xml>
     <Connector port="8443"     <Connector port="8443"
                protocol="org.apache.coyote.http11.Http11Nio2Protocol"                protocol="org.apache.coyote.http11.Http11Nio2Protocol"
Line 192: Line 215:
 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. 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>+<code xml>
     <Connector port="8085"     <Connector port="8085"
                protocol="org.apache.coyote.http11.Http11Nio2Protocol"                protocol="org.apache.coyote.http11.Http11Nio2Protocol"
Line 212: Line 235:
  
 Please configure the Stages hostname as it is used by the end users in ''$STAGES_CONF/config.properties'' as ''general.external.hostname'', e.g. 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>+<code properties>
 general.external.hostname = stages.example.com general.external.hostname = stages.example.com
 </code> </code>
Line 224: Line 247:
  
 ''$STAGES_CONF/stages.properties'' ''$STAGES_CONF/stages.properties''
-<code>+<code properties>
 general.external.hostname = stages.example.com general.external.hostname = stages.example.com
 general.keystore.path = conf/stages-self-signed-keystore.p12 general.keystore.path = conf/stages-self-signed-keystore.p12
 </code> </code>
 ''$STAGES_CONF/secret.properties'' ''$STAGES_CONF/secret.properties''
-<code>+<code properties>
 general.keystore.keyAlias = stages general.keystore.keyAlias = stages
 general.keystore.password = SECRET general.keystore.password = SECRET
Line 236: Line 259:
 For more details on certificate generation please refer to [[certificate_generation]]. 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.