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
79:configure_stages [2024/03/07 15:51] – Weinlein, Thomas79:configure_stages [2024/03/08 10:32] (current) – Weinlein, Thomas
Line 1: Line 1:
-====== Configure the Stages server  **Currently under rework** ======+====== Configure the Stages server ======
  
 ===== Stages installation location ===== ===== Stages installation location =====
Line 42: Line 42:
 | ''$STAGES_ROOT/config.bat'' (Windows) \\ ''$STAGES_ROOT/bin/rc.conf'' (Linux) | [[#Configuration of Stages Service Parameters]] |  **✔**  | | ''$STAGES_ROOT/config.bat'' (Windows) \\ ''$STAGES_ROOT/bin/rc.conf'' (Linux) | [[#Configuration of Stages Service Parameters]] |  **✔**  |
 | Basic configuration ||| | Basic configuration |||
-| ''$STAGES_CONF/server.xml'' | [[#Configuring the TCP Ports|Configuration of HTTP ports]] and [[#Configuring SSL Certificate|certificates]] |  **✔**((+| ''$STAGES_CONF/server.xml'' | [[#Configuring the TCP Ports|Configuration of HTTP ports]] and [[#configuring-tlsssl-certificate|certificates]] |  **✔**((
 by using variable replacement by using variable replacement
 ))  | ))  |
Line 63: Line 63:
 | ''$STAGES_CONF/signature.xml''  |  |  **✘**  | | ''$STAGES_CONF/signature.xml''  |  |  **✘**  |
 | ''$STAGES_CONF/licences'' |  |  **✘**  | | ''$STAGES_CONF/licences'' |  |  **✘**  |
-| [[#Configuring SSL Certificate|Certificates]] |||+| [[#configuring-tlsssl-certificate|Certificates]] |||
 | ''$STAGES_CONF/*.crt'' \\ ''$STAGES_CONF/*.p12'' \\ ''$STAGES_CONF/*.jks'' |  |  **✘**  | | ''$STAGES_CONF/*.crt'' \\ ''$STAGES_CONF/*.p12'' \\ ''$STAGES_CONF/*.jks'' |  |  **✘**  |
 | [[kerberos_autologin|Kerberos SSO]] ||| | [[kerberos_autologin|Kerberos SSO]] |||
Line 70: Line 70:
 | ''$STAGES_CONF/krb5.conf'' |   |  **✔**  | | ''$STAGES_CONF/krb5.conf'' |   |  **✔**  |
 | Metamodels and customisations ||| | Metamodels and customisations |||
-| '''$STAGES_CONF/model''' | [[install#install-customer-specific-metamodel-if-available|Metamodels]] |  **✔**  | +| ''$STAGES_CONF/model'' | [[install#install-customer-specific-metamodel-if-available|Metamodels]] |  **✔**  | 
-| '''$STAGES_CONF/local*.properties''' | [[#Local Message Customization|Custom message properties]] |  **✔**  | +| ''$STAGES_CONF/local*.properties'' | [[#Local Message Customization|Custom message properties]] |  **✔**  | 
-| '''$STAGES_CONF/fonts''' | [[install/fonts79|Custom fonts]] for PDF printing and visualizations |  **✔**  |+| ''$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]]. **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]].
Line 82: Line 82:
 **Windows:** **Windows:**
  
-In case of changes to the service configurations 
-<code> 
-$STAGES_ROOT\bin\reinstallService.bat 
-</code> 
-always 
 <code> <code>
 net stop stages net stop stages
Line 125: Line 120:
  
 <code xml> <code xml>
-    <notification> +<notification> 
-        <serverurl>https://${general.external.hostname}/stages</serverurl> +    <serverurl>https://${general.external.hostname}/stages</serverurl> 
-        [...] +    [...] 
-    </notification>+</notification>
 </code> </code>
  
Line 143: Line 138:
 <code xml> <code xml>
 <properties> <properties>
- <property name="name.of.property" value="value.of.property"/>+    <property name="name.of.property" value="value.of.property"/>
 </properties> </properties>
  
Line 152: Line 147:
 ==== Configuration of Stages Service Parameters ==== ==== Configuration of Stages Service Parameters ====
  
-For configuring Stages service please proceed as follows:+For configuring Stages service please proceed as follows. In this example the max heap memory is changed.
  
   * Windows:   * Windows:
Line 179: Line 174:
 The server.xml for new installations looks as follows: [[server.xml]] 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 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''.+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. When you try to access Stages via HTTP the client will be redirect to HTTPS instead.
Line 186: Line 181:
  
 <code xml> <code xml>
-    <Connector port="443" +<Connector  
-               protocol="org.apache.coyote.http11.Http11Nio2Protocol" +    port="443" 
-               URIEncoding="UTF-8" +    protocol="org.apache.coyote.http11.Http11Nio2Protocol" 
-               maxHttpHeaderSize="8192" +    URIEncoding="UTF-8" 
-               maxThreads="500" +    maxHttpHeaderSize="8192" 
-               minSpareThreads="50" +    maxThreads="500" 
-               enableLookups="false" +    minSpareThreads="50" 
-              [...] +    enableLookups="false" 
-     </Connector>+    [...] 
 +</Connector>
 </code> </code>
  
Line 200: Line 196:
  
 <code xml> <code xml>
-    <Connector port="8443" +<Connector port="8443" 
-               protocol="org.apache.coyote.http11.Http11Nio2Protocol" +    protocol="org.apache.coyote.http11.Http11Nio2Protocol" 
-               URIEncoding="UTF-8" +    URIEncoding="UTF-8" 
-               maxHttpHeaderSize="8192" +    maxHttpHeaderSize="8192" 
-               maxThreads="500" +    maxThreads="500" 
-               minSpareThreads="50" +    minSpareThreads="50" 
-               enableLookups="false" +    enableLookups="false" 
-              [...] +    [...] 
-     </Connector>+</Connector>
 </code> </code>
  
Line 216: Line 212:
  
 <code xml> <code xml>
-    <Connector port="8085" +<Connector port="8085" 
-               protocol="org.apache.coyote.http11.Http11Nio2Protocol" +    protocol="org.apache.coyote.http11.Http11Nio2Protocol" 
-               proxyName="${general.external.hostname}" +    proxyName="${general.external.hostname}" 
-               proxyPort="443" +    proxyPort="443" 
-               secure="true" +    secure="true" 
-               scheme="https" +    scheme="https" 
-               URIEncoding="UTF-8" +    URIEncoding="UTF-8" 
-               maxHttpHeaderSize="8192" +    maxHttpHeaderSize="8192" 
-               maxThreads="150" +    maxThreads="150" 
-               minSpareThreads="25" +    minSpareThreads="25" 
-               enableLookups="true" +    enableLookups="true" 
-               acceptCount="100" +    acceptCount="100" 
-               connectionTimeout="60000" +    connectionTimeout="60000" 
-               disableUploadTimeout="true" +    disableUploadTimeout="true" 
-               address="127.0.0.1" +    address="127.0.0.1" 
-      />+/>
 </code> </code>
  
Line 241: Line 237:
 In case you use a IPv6 only configuration please replace ''address="127.0.0.1"'' by ''address="::1"'' In case you use a IPv6 only configuration please replace ''address="127.0.0.1"'' by ''address="::1"''
  
-==== Configuring SSL Certificate ====+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. 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.
-Please store your PKCS keystore in ''$STAGES_CONF'' directory and adapt the following configuration properties accordingly:+  * 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'' ''$STAGES_CONF/stages.properties''
Line 257: Line 257:
 </code> </code>
  
-For more details on certificate generation please refer to [[certificate_generation]]. +[[#apply-configuration-changes|Apply the configuration changes]]
 ==== Configuration for usage with Reverse Proxy ==== ==== 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.+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. E.g.
Line 279: Line 278:
                scheme="https"                scheme="https"
                secure="true"                secure="true"
-               proxyname="${general.external.hostname}" +               proxyName="${general.external.hostname}" 
-               proxyport="443"+               proxyPort="443"
                address="127.0.0.1"                address="127.0.0.1"
                >                >
Line 332: Line 331:
 set JAVA_OPTS=[...] -Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL set JAVA_OPTS=[...] -Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL
 </code> </code>
-This is the default for new installations of 7.9.14.0 and newer.+This is the default for new installations of Stages 7.9.14.0 or newer.
  
 Linux: Linux:
Line 341: Line 340:
 ===== Licenses ===== ===== 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+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 ===== ===== Local Message Customization =====