Differences

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

--- 79:configure_stages_new [2024/03/07 14:32] – [Configuring the TCP Ports] Weinlein, Thomas
+++ 79:configure_stages_new [2024/03/12 10:17] (current) – removed Weinlein, Thomas
@@ Line 1: / Line 1: @@
-====== Configure the Stages server  **Currently under rework** ======
-===== Stages installation location =====
-The Stages installation location is referenced in this document as ''<STAGES_HOME>'' or ''$STAGES_ROOT'' which is the environment variable used by Stages to determine its base directory. The default location for ''$STAGES_ROOT'' is:
-Windows:
-<code ->
-C:\methodpark\stages\
-</code>
-Linux:
-<code ->
-/opt/stages/
-</code>
-===== Stages file structure =====
-In the ''$STAGES_ROOT'' directory you will find the following subdirectories:
-^ Directory ^ Usage ^ customizations possible ^
-| bin | Commandline tools |  **✘**((
-with exception of rc.conf on Linux
-))  |
-| cmd-lib | Libraries for commandline tools |  **✘**  |
-| conf | Configuration files directory referenced as ''$STAGES_CONF'' |  **✔**  |
-| data-cache  | Preprocessed configuration files and file cache for CMS data |  **✘**((
-could be deleted and will be recreated automatically
-))  |
-| elasticsearch | Local Elastic search server used for Stages full text search feature |  **✘**  |
-| lib | Customer specific libraries, i.e. JDBC database driver and custom integrations. Directory is referenced as ''$STAGES_LIB'' |  **✔**  |
-| local | internal use |  **✔**  |
-| logs  | Stages log files for error analysis. Directory is referenced as ''$STAGES_LOGS'' |  **✔**  |
-| tomcat | Tomcat application server with Stages application |  **✘**  |
-==== Important configuration files ====
-^ File ^ Usage ^ Shareable ^
-| Global |||
-| ''$STAGES_ROOT/config.bat'' (Windows) \\ ''$STAGES_ROOT/bin/rc.conf'' (Linux) | [[#Configuration of Stages Service Parameters]] |  **✔**  |
-| Basic configuration |||
-| ''$STAGES_CONF/server.xml'' | [[#Configuring the TCP Ports|Configuration of HTTP ports]] and [[#Configuring SSL Certificate|certificates]] |  **✔**((
-by using variable replacement
-))  |
-| ''$STAGES_CONF/config.xml'' | [[#Configuration File|Stages configuration]] |  **✔**((
-by using variable replacement
-))  |
-| ''$STAGES_CONF/database.properties'' | Stages database connection configuration for [[install#Establish database connection with MySQL|MySQL]] or [[install#Establish database connection with Oracle|OracleDB]] |  **✔**((
-by using variable replacement
-))  |
-| ''$STAGES_CONF/config.properties'' | Properties used for [[#variable replacement]]  |  **✘**((
-property values are server specific
-))  |
-| ''$STAGES_CONF/secret.properties'' | Properties used for [[#variable replacement]] of passwords and other secrets |  **✘**((
-property values are server specific
-))  |
-| ''$STAGES_CONF/rewrite-customer.config'' | Custom URL rewriting |  **✘**  |
-| ''$STAGES_CONF/log4j-customer.xml'' | Customisation of logging |  **✘**  |
-| [[#Licenses|Stages license files]] |||
-| ''$STAGES_CONF/license.xml'' |  |  **✘**  |
-| ''$STAGES_CONF/signature.xml''  |  |  **✘**  |
-| ''$STAGES_CONF/licences'' |  |  **✘**  |
-| [[#Configuring SSL Certificate|Certificates]] |||
-| ''$STAGES_CONF/*.crt'' \\ ''$STAGES_CONF/*.p12'' \\ ''$STAGES_CONF/*.jks'' |  |  **✘**  |
-| [[kerberos_autologin|Kerberos SSO]] |||
-| ''$STAGES_CONF/jaas.conf'' |  |  **✘**  |
-| ''$STAGES_CONF/*.keytab'' |  |  **✘**  |
-| ''$STAGES_CONF/krb5.conf'' |   |  **✔**  |
-| Metamodels and customisations |||
-| '''$STAGES_CONF/model''' | [[install#install-customer-specific-metamodel-if-available|Metamodels]] |  **✔**  |
-| '''$STAGES_CONF/local*.properties''' | [[#Local Message Customization|Custom message properties]] |  **✔**  |
-| '''$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]].
-===== Best practice for managing configurations =====
-Especially for administration of multiple Stages servers - i.e. for test and production - it is important to keep the configurations in sync to ensure results from one server are reproducible on the other server.
-We therefore strongly recommend to use the variable replacement feature to extract all server specific configuration values into the config.properties and secret.properties files.
-==== Variable replacement ====
- - requires Stages ''7.9.14.0'' or newer -
-This allows to keep the critical configuration files ''server.xml'', ''config.xml'' and ''database.properties'' server independent and therefore shareable, while e.g. environment specific server names and passwords are managed in the server specific config.properties and secret.properties files.
-A property in config.properties or secret.properties in the format
-<code properties>
-key = value
-</code>
-. E.g.
-<code properties>
-general.external.hostname = stages.example.com
-</code>
-The property can be used as a variable in ''server.xml'', ''config.xml'' and ''database.properties'' in the format ''${key}'' and that will be replaced by the corresponding value. E.g. in ''config.xml''
-<code xml>
-    <notification>
-        <serverurl>https://${general.external.hostname}/stages</serverurl>
-        [...]
-    </notification>
-</code>
-In case the same property is defined in ''config.properties'' and ''secret.properties'', ''secret.properties'' value is prefered.
-===== General Configuration of Stages =====
-==== Configuration File ====
-Stages can be configured in the ''$STAGES_CONF/conf/config.xml'' configuration file. In its properties section some parameters can be configured by introducing name-value pairs. For information about existing configuration parameters and their effect please contact the Stages support.
-The following code configures a value of “value.of.property” for the configuration property “name.of.property”:
-<code xml>
-<properties>
- <property name="name.of.property" value="value.of.property"/>
-</properties>
-</code>
-Please read also [[#Best practice for managing configurations]]
-==== Configuration of Stages Service Parameters ====
-For configuring Stages service please proceed as follows:
-  * Windows:
-      * Open file "$STAGES_ROOT\config.bat"
-      * Modify the red colored 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**
-      * Restart Stages service: **net start stages**
-  * 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"//
-      * Restart the Stages service:** stages restart**
-You can configure additional Java start parameter for Stages that are listed below:
-  * -Xmx (Max memory pool): 4048 MB
-  * -Xms (Initial memory pool): 4048 MB
-==== Java Garbage Collection Strategies ====
-The JavaVM provides a variety of different garbage collection strategies (algorithms). These different algorithms can have a huge impact on the performance of Java applications. Our internal tests have shown that for most customer scenarios the default garbage collector gives the best results. Therefore we advice our customers to leave the garbage collector settings for Stages unchanged.
-==== Configuring the TCP Ports ====
-Stages comes with HTTPS configured by default.
-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''.
-When you try to access Stages via HTTP the client will be redirect to HTTPS instead.
-To change the HTTPS port, change the port number within the following statement:
-<code xml>
-    <Connector port="443"
-               protocol="org.apache.coyote.http11.Http11Nio2Protocol"
-               URIEncoding="UTF-8"
-               maxHttpHeaderSize="8192"
-               maxThreads="500"
-               minSpareThreads="50"
-               enableLookups="false"
-              [...]
-     </Connector>
-</code>
-For example, to use HTTPS on port 8443, comment out the statement above and enable the statement below:
-<code xml>
-    <Connector port="8443"
-               protocol="org.apache.coyote.http11.Http11Nio2Protocol"
-               URIEncoding="UTF-8"
-               maxHttpHeaderSize="8192"
-               maxThreads="500"
-               minSpareThreads="50"
-               enableLookups="false"
-              [...]
-     </Connector>
-</code>
-=== Port 8085 for internal communication ===
-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 xml>
-    <Connector port="8085"
-               protocol="org.apache.coyote.http11.Http11Nio2Protocol"
-               proxyName="${general.external.hostname}"
-               proxyPort="443"
-               secure="true"
-               scheme="https"
-               URIEncoding="UTF-8"
-               maxHttpHeaderSize="8192"
-               maxThreads="150"
-               minSpareThreads="25"
-               enableLookups="true"
-               acceptCount="100"
-               connectionTimeout="60000"
-               disableUploadTimeout="true"
-               address="127.0.0.1"
-      />
-</code>
-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 properties>
-general.external.hostname = stages.example.com
-</code>
-In case you use a IPv6 only configuration please replace ''address="127.0.0.1"'' by ''address="::1"''
-==== Configuring 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.
-Please store your PKCS keystore in ''$STAGES_CONF'' directory and adapt the following configuration properties accordingly:
-''$STAGES_CONF/stages.properties''
-<code>
-general.external.hostname = stages.example.com
-general.keystore.path = conf/stages-self-signed-keystore.p12
-</code>
-''$STAGES_CONF/secret.properties''
-<code>
-general.keystore.keyAlias = stages
-general.keystore.password = SECRET
-</code>
-For more details on certificate generation please refer to [[certificate_generation]].
-__TODO__
-Explain proxyname proxyport secure?
-Configuration with reverse proxy
-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.
-Import certificate into system truststore (windows/Linux)
-===== 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
-===== Local Message Customization =====
-The messages shown on the Stages Graphical User Interface (GUI) can be customized to the terminology used within an organization. This also applies to the textual representations for the configured news application categories.
-Each message possesses a standard definition which can be overwritten by local definitions. These local messages can be configured in the file ''$STAGES_CONF/local.properties''  and its localized versions (e.g. ''$STAGES_CONF/local_de.properties''). At system startup, your messages will be automatically merged into the message pool of Stages.
-The format of the message files conforms to the Java property files standard ("name = value").
-===== CMS Configuration =====
-Stages can interact with configuration management systems to work with remotely stored files. Please find the details of the configuration [[cms_configuration|here]].
-==== CMS Prefetch configuration ====
-Please find the details [[cms_prefetch|here]].
-==== Document Lifecycles ====
-Please find the details [[document_lifestyles|here]]
-===== Email Notifications =====
-Please find the details [[email_notification|here]].
-===== LDAP Synchronization =====
-Please find the details [[ldap|here]].