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:upgrade_to_7_9_14 [2024/03/14 15:01] – [Upgrade to release 7.9.14.0 or higher (wip)] Weinlein, Thomas79:upgrade_to_7_9_14 [2024/04/02 12:02] (current) – [Upgrade to release 7.9.14.0 or higher] Weinlein, Thomas
Line 1: Line 1:
-====== Upgrade to release 7.9.14.0 or higher (wip) ======+====== Upgrade to release 7.9.14.0 or higher ======
  
 With this release we simplify the initial setup of Stages for production and follow a security by default approach. With this release we simplify the initial setup of Stages for production and follow a security by default approach.
-Therefore the default configuration for new Stages installations is prepared for **HTTPS only** access to Stages. To be able to configure the latest TLS version 1.3 it is necessary to update the Java JDK 8 version on the server to **at least ''JDK-8u301''** or any higher 1.8.x version (64-Bit). Latest JDK 8 patch version is recommended.+Therefore the default configuration for new Stages installations is prepared for **HTTPS only** access to Stages. For existing installation - after the upgrade to Stages 7.9.14.0 or higher - a few manual steps are necessary as outlined below.
  
-The error prone configuration for report execution and PDF printing was also unified and delivered by default. The internal Stages communication will now always use a separate connector on port ''8085''.+To be able to configure and use the latest TLS version 1.3 it is necessary to update the Java JDK 8 version on the server to **at least ''JDK-8u381''** or any higher 1.8.x version (64-Bit). Latest JDK 8 patch version is recommended.
  
-To simplify the management of configurations for test and production servers, the variable replacement mechanism of config.xml was extended to server.xml and database.properties files. This should it make easier to sync the general Stages configuration between test and production environments while maintaining individual configuration values in just two files named config.properties and secret.properties. Please read [[configure_stages]] for more details.+The formerly error prone configuration for report execution and PDF printing is now also unified and delivered by default. The internal Stages communication will always use a separate connector on port ''8085'' that is not reachable from the outside. 
 + 
 +To simplify the management of configurations for test and production servers, the variable replacement mechanism of ''config.xml'' was extended to ''server.xml'' and ''database.properties'' files. This should make it easier to sync the general Stages configuration between test and production environments while maintaining individual configuration values in just two files named ''config.properties'' and ''secret.properties''. Please read [[configure_stages]] for more details on that topic.
    
 The following manual configuration changes need to be applied for installations that are [[#Stages server is already configured for HTTPS|configured for HTTPS usage]], meaning you can reach Stages via http**s** e.g. ''%%http%%**s**%%://mystages.mycompany.com%%''. For test server installations that are currently NOT prepared for HTTPS please [[#Stages server does not yet support HTTPS|follow these instructions]]. The following manual configuration changes need to be applied for installations that are [[#Stages server is already configured for HTTPS|configured for HTTPS usage]], meaning you can reach Stages via http**s** e.g. ''%%http%%**s**%%://mystages.mycompany.com%%''. For test server installations that are currently NOT prepared for HTTPS please [[#Stages server does not yet support HTTPS|follow these instructions]].
  
-==== Stages server is already configured for HTTPS ====+===== Stages server is already configured for HTTPS =====
  
 === config.properties === === config.properties ===
Line 51: Line 53:
  
 === Apply configuration changes === === Apply configuration changes ===
-[[configure_stages#apply-configuration-changes|Execute update and restart stages]]+Execute the configuration update and restart Stages as outlined [[configure_stages#apply-configuration-changes|here]]
  
 === Access Stages === === Access Stages ===
Line 57: Line 59:
  
  
-==== Stages server does not yet support HTTPS ====+===== Stages server does not yet support HTTPS =====
  
 As Stages will now enforce usage of HTTPS additional steps are necessary, when you upgrade from a HTTP only setup. As Stages will now enforce usage of HTTPS additional steps are necessary, when you upgrade from a HTTP only setup.
 +Stages comes by default with a self signed certificate for the domain stages.localhost which is just an alias for localhost. Therefore the default certificates are only useful for local access to Stages. The following steps will enable HTTPS access for your machine with the default self signed certificate. To access Stages from another machine without browser warnings, you need to [[configure_stages#configuring-tlsssl-certificate|create a certificate that is valid for your servers external hostname]] afterwards.
 +
    
 === Download self signed certificate === === Download self signed certificate ===
-TODO+Download the certificate keystore for the self signed certificate from here and store it in the ''$STAGES_CONF'' directory: 
 +https://download.methodpark.de/stages/stages-self-signed-cert/stages-self-signed-keystore.p12 
 +Download the self signed certificate to be able to import it into your systems truststore. This is only useful for pure local access to Stages. 
 +https://download.methodpark.de/stages/stages-self-signed-cert/stages-self-signed.crt 
  
 === config.properties === === config.properties ===
-Add the external hostname / DNS name of you Stages server as ''general.external.hostname'' into ''$STAGES_CONF/config.properties''. E.g.+Add the external hostname / DNS name of your Stages server as ''general.external.hostname'' into ''$STAGES_CONF/config.properties'', e.g. ''mystages.mycompany.com'', and configure the path to the certificate keystore file relative to ''$STAGES_ROOT'' as ''general.keystore.path''
 <code properties> <code properties>
 general.external.hostname = mystages.mycompany.com general.external.hostname = mystages.mycompany.com
Line 73: Line 81:
  
 === secret.properties === === secret.properties ===
 +Add the following two properties to ''$STAGES_CONF/secret.properties''
 <code properties> <code properties>
 general.keystore.keyAlias = stages general.keystore.keyAlias = stages
Line 102: Line 111:
 </code> </code>
  
-Additional it is recommended to replace the existing connector for HTTP port 80 or 8080 by the following two connectors that will ensure that Stages is listening on the HTTP and HTTPS ports and that HTTP requests are redirected to HTTPS. +Additionally it is recommended to replace the existing connector for HTTP port 80 or 8080 by the following two connectors that will ensure that Stages is listening on the HTTP and HTTPS ports and that HTTP requests are redirected to HTTPS. 
-In case you do not want to use the default ports 80 and 443, please adapt the configuration of the port and redirectPort attributes accordingly.+In case you do not want to use the default ports 80 and 443, but e.g. 8080 and 8443, please adapt the configuration of the ''port'' and ''redirectPort'' attributes accordingly.
 <code xml> <code xml>
    <Connector port="80"    <Connector port="80"
Line 157: Line 166:
  
 === Apply configuration changes === === Apply configuration changes ===
-[[configure_stages#apply-configuration-changes|Execute update and restart stages]]+Execute configuration update and restart Stages as outlined [[configure_stages#apply-configuration-changes|here]]
  
 === Access Stages === === Access Stages ===
-Verify that Stages is available under ''%%https://stages.localhost%%'' or ''%%https://mystages.mycompany.com%%''. Please note that the browser will complain that the provided certificate is not valid or trusted. For the initial test please acknowledge the risk and click through to Stages.  +Verify that Stages is available under ''%%https://stages.localhost%%'' when you open the browser on the server machine or ''%%https://mystages.mycompany.com%%''. Please note that the browser will complain that the provided certificate is not valid or trusted. For the initial test please acknowledge the risk and click through to Stages.  
-After that you should [[configure_stages#configuring-tlsssl-certificate|create and configure your own singed certificate]] or create your own self signed certificate and import it into your browsers truststore. +After that you should [[configure_stages#configuring-tlsssl-certificate|create and configure your own singed certificate]] or create your own self signed certificate and import it into your browsers or systems truststore. For pure local access to Stages you can import the default stages-self-signed.crt certificate as downloaded [[#Download self signed certificate|here]] into your browsers truststore.