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 16:24] – [Apply configuration changes] Weinlein, Thomas79:configure_stages [2024/03/08 10:32] (current) Weinlein, Thomas
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 120: 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 138: 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 147: 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 174: 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 181: 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 195: 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 211: 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 236: 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 #12 keystore file 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 252: 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 274: 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 327: 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 336: 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 =====