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:install [2023/04/19 11:38] – [Stages Installation on Linux] bdss79:install [2024/03/15 11:28] (current) – [Start without Root Privileges on Linux] Mrozek, Marek
Line 1: Line 1:
 ====== Basic Installation ====== ====== Basic Installation ======
 +
  
 ===== Perform basic installation on Windows ===== ===== Perform basic installation on Windows =====
  
-  * **Download and install Java Development Kit 8** + 
-      * see [[:79:system_requirements|System Requirements]] for supported variants +==== Download and install Java Development Kit 8 ==== 
-  * **Database installation with MySQL 8.0** + 
-      * Get MySQL database dump from [[stages-support@ul.com?subject=Stages database dump - MySQL|Stages Support]] +  * see [[:79:system_requirements|System Requirements]] for supported variants 
-      * Download MySQL Installer for MySQL 8.0 + 
-      * Install MySQL 8.0 + 
-        * Select Setup Type “Server only” is recommended +==== Database installation with MySQL 8.0 ==== 
-        * Install MySQL with config type “Server Machine”, default encoding “UTF-8” and service name “mysql80” + 
-        * Adapt/check the following properties within ”[mysql]“ and ”[mysqld]“ section in "C:\ProgramData\MySQL\MySQL Server 8.0\my.ini" configuration file+  * Get MySQL database dump from [[stages-support@ul.com?subject=Stages database dump - MySQL|Stages Support]] 
 +  * Download MySQL Installer for MySQL 8.0 
 +  * Install MySQL 8.0 
 +      * Select Setup Type “Server only” is recommended 
 +      * Install MySQL with config type “Server Machine”, default encoding “UTF-8” and service name “mysql80” 
 +      * Adapt/check the following properties within ”[mysql]“ and ”[mysqld]“ section in "C:\ProgramData\MySQL\MySQL Server 8.0\my.ini" configuration file
 <code> <code>
  
Line 53: Line 59:
 </code> </code>
  
-  * **Database installation with Oracle 11g, 12c or 19c** 
-      * Get Oracle database dump and installation instructions from [[stages-support@ul.com?subject=Stages database dump - Oracle|Stages Support]] 
  
-  * **Stages installation** +==== Database installation with Oracle 11g, 12c or 19c ==== 
-      * Execute Stages installer as administrator (will be sent to you by [[stages-support@ul.com?subject=Stages installation package - Windows|Stages Support]]) + 
-      * Establish database connection with **MySQL** +  * Get Oracle database dump and installation instructions from [[stages-support@ul.com?subject=Stages database dump - Oracle|Stages Support]] 
-        * Download MySQL JDBC connector (Connector/J 8.0 Platform Independent) MySQL 8.0 + 
-        * Copy JDBC connector to ”<stages installation path>/stages/lib“ and rename the file mysql-connector-java-*-bin.jar to mysql.jar + 
-        * Edit ”<Stages installation path>/stages/conf/database.properties“ appropriately like in the following example:+==== Stages installation on Windows ==== 
 + 
 +  * Execute Stages installer as administrator (will be sent to you by [[stages-support@ul.com?subject=Stages installation package - Windows|Stages Support]]) 
 + 
 +=== Establish database connection with MySQL === 
 + 
 +  * Download MySQL JDBC connector (Connector/J 8.0 Platform Independent) MySQL 8.0 
 +  * Copy JDBC connector to ”<stages installation path>/stages/lib“ and rename the file mysql-connector-java-*-bin.jar to mysql.jar 
 +  * Edit ”<Stages installation path>/stages/conf/database.properties“ appropriately like in the following example:
 <code> <code>
  
Line 71: Line 83:
  
 </code> </code>
 +  * Activate the configuration
 +      * Windows Start Menu: Execute “Programs > Method Park > Stages > Update Configuration”
 +  * Start Stages
 +      * Windows: Start the services “Stages Search” and then “Stages”
  
-  * Establish database connection with **Oracle** +=== Establish database connection with Oracle === 
-      * Download Oracle JDBC connector for your Oracle version + 
-      * Copy JDBC connector to ”<stages installation path>/stages/lib“ and rename it to “ojdbc.jar” +  * Download Oracle JDBC connector for your Oracle version 
-      * Edit ”<Stages installation path>/stages/conf/database.properties“ appropriately like in the following example:+  * Copy JDBC connector to ”<stages installation path>/stages/lib“ and rename it to “ojdbc.jar” 
 +  * Edit ”<Stages installation path>/stages/conf/database.properties“ appropriately like in the following example:
  
 <code> <code>
Line 92: Line 109:
   * Start Stages   * Start Stages
       * Windows: Start the services “Stages Search” and then “Stages”       * Windows: Start the services “Stages Search” and then “Stages”
 +
  
 ===== Perform basic installation on Linux ===== ===== Perform basic installation on Linux =====
Line 130: Line 148:
       * complete the installation with your organizational policy       * complete the installation with your organizational policy
       * Proceed with the steps provided below       * Proceed with the steps provided below
-        * Create Database, Database User and Grant Privileges+        * [[:79:install#create-database-database-user-and-grant-privileges|Create Database, Database User and Grant Privileges]]
  
  
Line 230: Line 248:
       * execute “stages start”       * execute “stages start”
  
 +==== (Optional) Start without Root Privileges on Linux ====
 +
 +Normally Stages is started by the "root" user and then drops its privileges to the "stages" user after successful startup. In high risk environments, Stages can now also be started with a user id other than root. It can be enabled via the ''STAGES_NONROOTSTART''  variable in ''…/bin/rc.conf''. If enabled, the same user id starting the service will also be used to run the service.
 +
 +Please note that privileged ports below 1024 cannot be opened in this configuration, so the normal HTTPS port 443 cannot be used. The non-root setting can only be used when the Tomcat connectors are configured to use ports higher than 1024 and e.g. a reverse proxy is being used to allow normal access via HTTPS.
 +
 +**How to configure the user that Stages service should run as?**
 + 
 +1. Edit stages.service file:
 +  * vi /etc/systemd/system/stages.service 
 +  * add the line User=<username> within the [Service] section (IMPORTANT: DO NOT ADD QUOTES AROUND THE USERNAME)
 +
 +2. Reload system manager configuration with systemctl command:
 +  * Unordered List Itemsystemctl daemon-reload
 +
 +3. Additionally change the user ownership for all files below stages installation folder with following command: 
 +  * chown -R <username> /opt/stages
  
 ===== (Optional) Secure MySQL connection with SSL ===== ===== (Optional) Secure MySQL connection with SSL =====
Line 277: Line 312:
       * Open file "<Stages installation path>\stages\config.bat"       * Open file "<Stages installation path>\stages\config.bat"
       * Modify the red colored setting: //set TOMCAT_OPTS=–JvmMx=       * Modify the red colored setting: //set TOMCAT_OPTS=–JvmMx=
- <font inherit/inherit;;#e74c3c;;inherit><RAM in MB></font> //+ <RAM in MB> //
       * //Open a cmd with administrative permissions and navigate to folder "<Stages installation path>\stages\bin"//       * //Open a cmd with administrative permissions and navigate to folder "<Stages installation path>\stages\bin"//
       * //Reinstall the Stages service: **reinstallService.bat** //       * //Reinstall the Stages service: **reinstallService.bat** //
Line 284: Line 319:
       * //Open file "<Stages installation path>/stages/bin/rc.conf"//       * //Open file "<Stages installation path>/stages/bin/rc.conf"//
       * //Modify the red colored value: //CONF_TOMCAT_OPTS="-Xmx       * //Modify the red colored value: //CONF_TOMCAT_OPTS="-Xmx
- <font inherit/inherit;;#e74c3c;;inherit><RAM in MB></font>  m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow"+ <RAM in MB>  m -XX:+UseG1GC -XX-OmitStackTraceInFastThrow"
  
   * Restart the Stages service: **stages restart**   * Restart the Stages service: **stages restart**
Line 324: Line 359:
 ===== Configure SSL ===== ===== Configure SSL =====
  
-To encrypt all connections between the users and Stages, we strongly recommend to configure SSL for the Stages server. \ In addition to the following guidelines, a detailed guide on how to easily configure SSL with Stages can be found [[http://www.methodpark.de/downloads/stages/static/documentation/Stages_SSL_configuration_guide.pdf|here]]. +Please refer to [[configure_stages#configuring-tlsssl-certificate|here]].
- +
-  * Ask for a DNS alias for the server, e.g. "stages.company.com" +
-  * Ask for a SSL certificate for the server which refers to the above alias. Depending on your local procedures, this might require creating a certificate request (see [[https://www.digicert.com/kb/csr-ssl-installation/tomcat-keytool.htm|https://www.digicert.com/kb/csr-ssl-installation/tomcat-keytool.htm]] for more info). +
-  * Import the SSL certificate into a keystore (see link above for more info) +
-  * Configure Tomcat to use this SSL certificate (see link above for more info). The relevant Tomcat config file is located in ''<Stages installation path>/stages/conf/server.xml''  and the SSL info needs to be configured for each ''<Connector>''  section. After updating the config file, run ''bin/update.sh''  or ''bin\update.bat''  to install it at the correct location. +
-  * To enforce redirection from http to https add the following to ''conf/web-customer.xml'', run ''bin/update.sh''  or ''bin\update.bat''  and restart Stages service +
-<code> +
- +
-<security-constraint> +
-    <display-name>Enforce HTTPS</display-name> +
-    <web-resource-collection> +
-        <web-resource-name>stages-public</web-resource-name> +
-    </web-resource-collection> +
-    <user-data-constraint> +
-        <description>Force SSL for all connections.</description> +
-        <transport-guarantee>CONFIDENTIAL</transport-guarantee> +
-    </user-data-constraint> +
-</security-constraint> +
- +
-</code>+
  
 === Add CAs to your TrustStore === === Add CAs to your TrustStore ===
  
-For using reports in Stages, you need to add your companies root certificate and all Intermediate certificates (if existing) to the server Java truststore. The Java truststore includes all trusted root certificates. If a report tries to connect via SSL to your Stages server, it will be not executed correctly, because Java does not trust the SSL certificate. It was not issued by a Java trusted certificate authority - included in the Java truststore. +Please refer to [[configure_stages#Use the system trust store|here]].
- +
-  * Import your companies root certificate and all intermediate certificates (if existing) into this file: \\ <Java Development Kit Installation Directory>\jre\lib\security\cacerts +
- +
-(Linux directories may varify) +
- +
-  * Please restart Stages service after applying changes to the Java Trust Store +
- +
 ===== Accessing Stages ===== ===== Accessing Stages =====
  
-''After successful installation process - Stages is accessible via web browser by URL [[https://localhost:8443|https://localhost:8443]] or [[http://localhost:8080|http://localhost:8080]] (depending on the SSL port) ''+After successful installation process - Stages is accessible via web browser by URL [[https://stages.localhost|https://stages.localhost]]. As Stages is delivered with a self signed certificate your browser will warn you that the certificate is not trustworthy. For a first test you can instruct the browser to direct you to the website anyhow. After that please [[configure_stages#Configuring SSL Certificate|configure a trusted certificate]].
  
 ===== Change password of "root" user ===== ===== Change password of "root" user =====
  
-''Log in with the "root" user and the provided password. Click on the "Superuser" link in the bottom left corner of the navigation and change the password to a secure and unique one. ''+Log in with the "root" user and the provided password. Click on the "Superuser" link in the bottom left corner of the navigation and change the password to a secure and unique one. 
  
 ===== Prepare Stages for productive usage ===== ===== Prepare Stages for productive usage =====