OpenRIMS-RPM - Installation Part 1: Difference between revisions

From OpenRIMS Wiki
Jump to navigation Jump to search
VisualWikitext
m (Khoppenworth moved page Installation Part1 to OpenRIMS - Installation Part 1 without leaving a redirect)
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:


= Objective =
== Purpose ==
              This document helps deploy Pharmadex 2 software first time, along with the demo database.
This document describes deployment of OpenRIMS software on a default server.


The audience of it is IT persons that are responsible to install and maintain the Pharmadex 2 software. Minimal qualification requirements are:
The audience of it is IT persons that are responsible to install and maintain the OpenRIMS software.


·       Ability to install and configure programs and components in the selected Operation System.
You should have the ability to install and configure programs and components/services in the selected operating system.


·       The MySQL knowledge.
Additionally you need experience on MySQL.


== Pre-conditions ==
!'''PLEASE READ THE FULL DOCUMENT BEFORE PROCEDING WITH THE INSTALLATION!'''
              Regardless of deployment configuration selected, the following pre-conditions should be fulfilled:


·       At least 2 GB of free RAM
== Overview of Server Requirements ==
Regardless of deployment configuration selected, the following pre-conditions should be fulfilled:


·       At least 10GB of free SDD/HDD
=== Hardware Requirements ===
{| class="wikitable"
|+Recommendation
|
|'''Initial Configuration and Testing Server'''
|'''Production Server'''
|-
|CPU
|1-2 cores
|8 cores
|-
|Memory
|At least 2 GB of free RAM
|At least 16 GB of free RAM
|-
|Harddrive
|At least 10GB of free SDD/HDD
|At least 10GB of free SDD/HDD
|-
|Internet connection
|Should align with minimal requirements for Google Mail
|Should align with minimal requirements for Google Mail
|}


·       Operation Systems:
=== Software Requirements ===
{| class="wikitable"
|Operating System
|Linux, released after 2018. Tested on Ubuntu 18.04.4 LTS and above
OR


o  Windows Server 2016 and above
Windows Server 2016 and above
|
|-
|Database:
|MySQL : Server 5.7 and Workbench 8.0
|
|-
|Java:
|Oracle Java JDK 1.8
OR


o  Windows 10
OpenJDK 1.8


o  Linux, released after 2018. Tested on Ubuntu 18.04.4 LTS and above
''(OpenJDK 1.8 has been tested on Linux Ubuntu, but not Windows)''
|
|-
|OpenRIMS application & database:
|OpenRIMS Java application binary
AND


·       MySQL R 5.7
OpenRIMS demo database


o  Server
(<nowiki>https://github.com/MSH/Pharmadex2/tree/main/database</nowiki>[1])


o  Workbench
''(Please refer to the README.md file)''
|
|-
|Google Oauth ID & Secret
|A Google Mail account for OAuth Login SSO
|
|}


·       Oracle Java JDK 1.8. OpenJDK 1.8 has been tested on Linux Ubuntu, but not Windows
== The OpenRIMS Installation Procedure ==


·       Internet connection. Properties of it should suit minimal requirements for Google Mail
=== Prepare to install ===
1.      Install the following using the respective vendor’s deployment manuals:


·       Binary Pharmadex 2 distribution (see below)
1.1.   MySQL 5.7 : Server 5.7 and Workbench 8.0


·       Pharmadex 2 demo database (<nowiki>https://github.com/MSH/Pharmadex2/tree/main/database</nowiki>[1])
1.2.   Java JDK 1.8
 
2.      Restore the main database INCLUDING stored procedures to MySQL using MySQL Workbench or the command line. Name it '''pdx2'''. Verify that the stored procedures have been imported!
 
''Ubuntu MySQL CLI hint (<code>CREATE DATABASE pdx2</code>. And restore it: $ <code>mysql -u username -p pdx2 < DumpPdx2.sql</code>)''
 
3.      Copy the binary application <code>pharmadex2-0.0.1.jar</code> and <code>application.properties</code> to a dedicated user folder, e.g. /home/{username}/applications/openrims
 
== Post-Installation OpenRIMS Configurations ==
 
=== Local TCP/IP port ===
Adjust the application.properties file for initial configuration as described below.
 
When initial configuration is concluded you should disable Variables Edit and Cloning of Workflows.
 
==== Database ====
In the application.properties file edit the values marked bold:
 
<code>spring.datasource.url = jdbc:mysql://localhost/'''openrimsre'''?useSSL=false&useUnicode=yes&characterEncoding=UTF-8&characterSetResults=UTF-8&'''serverTimezone=Europe/Kiev'''</code>
 
<code>spring.datasource.username = '''username'''</code>
 
<code>spring.datasource.password = '''password'''</code>
 
==== '''File Size Limit for Upload''' ====
Large file uploads can be enabled but is not recommended. A separate repository should be identified like a Document Management System (DMS) e.g. Alfresco Community Edition or Google Drive.
 
To enable large file upload the server administrator must (''example is max 200Mb file''):
 
# Add following line to MySQL configuration file in the [mysqld] section: <code>max_allowed_packet=200Mb</code>
# Modify the following two lines in the application.properties file: <code>spring.servlet.multipart.max-file-size=200MB</code> <code>spring.servlet.multipart.max-request-size=200MB</code>
 
==== Logs ====
In the application.properties file edit the values marked bold:
 
<code>logging.file.path=/'''home/user/openrimsre/log'''</code>
 
<code>Recommended setting: '''logging.file.path= ./log/'''</code>
 
After configuration it will be necessary to copy Client ID and Client secret to the application.properties
 
==== OATH2 ====
<code>spring.security.oauth2.client.registration.google.client-id=client_id</code>
 
<code>spring.security.oauth2.client.registration.google.client-secret=client_secret</code>
 
==== '''SMTP Configuration''' ====
<nowiki>#</nowiki> SMPT Outgoing email settings
 
<code>spring.mail.username=NRAemail@gmail.com</code>
 
<code>spring.mail.password=MyPassword</code>
 
==== '''Allow System Edits for initial workflow configuration''' ====
<nowiki>##</nowiki> Developer Mode Status
 
<code>variables.properties.edit=true</code>
 
==== '''Allow Cloning of Workflows for initial workflow configuration''' ====
<code>pharmadex.allow.process.import=true</code>
 
== Install OpenRIMS as a service ==
Examples of the configurations are in the binary distributive on/from GitHub. The folders are “Windows” and “Linux”.
 
'''Linux'''


·       The own, private Google Mail account
The official guide is here https://docs.spring.io/spring-boot/docs/current/reference/html/deployment.html#deployment.installing.nix-services.system-d


== Pharmadex 2 binary distribution ==
Here are detailed steps for Ubuntu 22.04:
The possibility to build the Pharmadex 2 software directly from the source codes is possible, however is not covered by this document. However, this manual describes deployment from the binary distribution. For current, the MSH staff may get this distribution from the corporative GitHub, address is


              The descriptions of binary components may be found in the respective file README.md
# Copy file .service to /etc/systemd/system: <code>sudo cp openrims.service /etc/systemd/system</code>
# Edit file .service and change Username '''and''' Execstart path.
# Start the service: <code>systemctl enable openrims.service</code>
# Change Owner of the java application to your user: <code>sudo chmod a+rwx /home/ubuntu/applications/pharmadex2/pharmadex2-0.0.1.jar</code> OR <code>sudo cdmod 500 pharmadex2-0.0.1.jar</code>


= Steps to deploy =
For reference here is a sample service file:<blockquote><code>[Unit]</code>


== Prepare to install ==
<code>Description=Pharmadex 2 UAT version (madagascar)</code>
1.      Install using the vendor’s deployment manual:


1.1.   MySQL
<code>After=pharmadex.service</code>


1.2.   Java JDK 1.8
<code>[Service]</code>
 
<code>User=ubuntu</code>
 
<code>ExecStart=/home/{username}/applications/openrims/pharmadex2-0.0.1.jar</code>
 
<code>SuccessExitStatus=143</code>
 
<code>[Install]</code>
 
<code>WantedBy=multi-user.target</code></blockquote>
'''For Windows'''
 
The official guide is here https://docs.spring.io/spring-boot/docs/current/reference/html/deployment.html#deployment.installing.windows-services
 
== Provide access from the Internet ==
To provide access from the Internet it will be a good idea to establish a proxy gateway like Nginx or Apache2.
 
The example of virtual server configuration for Apache 2 is in the binary distributive folder named “Linux” on GitHub.
 
For Ubuntu 22.04 and Apache2 here are the steps:
 
# Copy pharmadex.conf to apache folder e.g. /etc/apache2/sites-available
# Enable the site a2ensite pharmadex
Here is another sample Apache conf file with https enabled by [https://www.digitalocean.com/community/tutorials/how-to-use-certbot-standalone-mode-to-retrieve-let-s-encrypt-ssl-certificates-on-ubuntu-20-04 Letsencrypt]:<blockquote><VirtualHost *:80>
 
ServerName openrims.yourdomain.com
 
Redirect permanent / <nowiki>https://openrims.yourdomain.com/</nowiki>
 
</VirtualHost>
 
 
<VirtualHost *:443>
 
ServerName openrims.yourdomain.com
 
SSLEngine On
 
SSLCertificateFile C:\Certbot\live\openrims.yourdomain.com\fullchain.pem
 
SSLCertificateKeyFile C:\Certbot\live\openrims.yourdomain.com\privkey.pem
 
SSLProtocol         all -SSLv3 -TLSv1 -TLSv1.1
 
SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256


2.      Restore the demo database to MySQL using MySQL Workbench or the command line
SSLHonorCipherOrder on


3.      Copy the binary application pharmadex2-0.0.1.jar  and application.properties to the dedicated folder, e.g. applications/pharmadex2
SSLCompression      off


== Configure ==
SSLSessionTickets   off


== Local TCP/IP port ==
SSLSessionCacheTimeout  300
In the application.properties file edit the values marked bold (if it will be necessary):


=== Database ===
ProxyPreserveHost On
              In the application.properties file edit the values marked bold:


spring.datasource.url = jdbc:mysql://localhost/pdx2?useSSL=false&useUnicode=yes&characterEncoding=UTF-8&characterSetResults=UTF-8&'''serverTimezone=Europe/Kiev'''
<Location />


spring.datasource.username = '''username'''
ProxyPass <nowiki>http://192.168.1.10:8084/</nowiki>


spring.datasource.password = '''password'''
ProxyPassReverse <nowiki>http://192.168.1.10:8084/</nowiki>


=== Logs ===
</Location>
              In the application.properties file edit the values marked bold:


logging.file.path=/'''home/alexk/pharmadex/log'''
</VirtualHost>"</blockquote>


the good choice is:
== Configuring Google Authentication ==
LINK: See [[OpenRIMS - Installation Part 2]]


'''logging.file.path= ./log/'''
== Special Configuration ==
----[1] This repository is not public yet.
LINK: See '''[[Installation part 3|IIS as a gateway for Spring Boot application]]'''
----[1] For current, available only to MSH staff

Latest revision as of 15:49, 23 July 2024

Purpose

This document describes deployment of OpenRIMS software on a default server.

The audience of it is IT persons that are responsible to install and maintain the OpenRIMS software.

You should have the ability to install and configure programs and components/services in the selected operating system.

Additionally you need experience on MySQL.

!PLEASE READ THE FULL DOCUMENT BEFORE PROCEDING WITH THE INSTALLATION!

Overview of Server Requirements

Regardless of deployment configuration selected, the following pre-conditions should be fulfilled:

Hardware Requirements

Recommendation
Initial Configuration and Testing Server Production Server
CPU 1-2 cores 8 cores
Memory At least 2 GB of free RAM At least 16 GB of free RAM
Harddrive At least 10GB of free SDD/HDD At least 10GB of free SDD/HDD
Internet connection Should align with minimal requirements for Google Mail Should align with minimal requirements for Google Mail

Software Requirements

Operating System Linux, released after 2018. Tested on Ubuntu 18.04.4 LTS and above

OR

Windows Server 2016 and above

Database: MySQL : Server 5.7 and Workbench 8.0
Java: Oracle Java JDK 1.8

OR

OpenJDK 1.8

(OpenJDK 1.8 has been tested on Linux Ubuntu, but not Windows)

OpenRIMS application & database: OpenRIMS Java application binary

AND

OpenRIMS demo database

(https://github.com/MSH/Pharmadex2/tree/main/database[1])

(Please refer to the README.md file)

Google Oauth ID & Secret A Google Mail account for OAuth Login SSO

The OpenRIMS Installation Procedure

Prepare to install

1.      Install the following using the respective vendor’s deployment manuals:

1.1.   MySQL 5.7 : Server 5.7 and Workbench 8.0

1.2.   Java JDK 1.8

2.      Restore the main database INCLUDING stored procedures to MySQL using MySQL Workbench or the command line. Name it pdx2. Verify that the stored procedures have been imported!

Ubuntu MySQL CLI hint (CREATE DATABASE pdx2. And restore it: $ mysql -u username -p pdx2 < DumpPdx2.sql)

3.      Copy the binary application pharmadex2-0.0.1.jar and application.properties to a dedicated user folder, e.g. /home/{username}/applications/openrims

Post-Installation OpenRIMS Configurations

Local TCP/IP port

Adjust the application.properties file for initial configuration as described below.

When initial configuration is concluded you should disable Variables Edit and Cloning of Workflows.

Database

In the application.properties file edit the values marked bold:

spring.datasource.url = jdbc:mysql://localhost/openrimsre?useSSL=false&useUnicode=yes&characterEncoding=UTF-8&characterSetResults=UTF-8&serverTimezone=Europe/Kiev

spring.datasource.username = username

spring.datasource.password = password

File Size Limit for Upload

Large file uploads can be enabled but is not recommended. A separate repository should be identified like a Document Management System (DMS) e.g. Alfresco Community Edition or Google Drive.

To enable large file upload the server administrator must (example is max 200Mb file):

  1. Add following line to MySQL configuration file in the [mysqld] section: max_allowed_packet=200Mb
  2. Modify the following two lines in the application.properties file: spring.servlet.multipart.max-file-size=200MB spring.servlet.multipart.max-request-size=200MB

Logs

In the application.properties file edit the values marked bold:

logging.file.path=/home/user/openrimsre/log

Recommended setting: logging.file.path= ./log/

After configuration it will be necessary to copy Client ID and Client secret to the application.properties

OATH2

spring.security.oauth2.client.registration.google.client-id=client_id

spring.security.oauth2.client.registration.google.client-secret=client_secret

SMTP Configuration

# SMPT Outgoing email settings

spring.mail.username=NRAemail@gmail.com

spring.mail.password=MyPassword

Allow System Edits for initial workflow configuration

## Developer Mode Status

variables.properties.edit=true

Allow Cloning of Workflows for initial workflow configuration

pharmadex.allow.process.import=true

Install OpenRIMS as a service

Examples of the configurations are in the binary distributive on/from GitHub. The folders are “Windows” and “Linux”.

Linux

The official guide is here https://docs.spring.io/spring-boot/docs/current/reference/html/deployment.html#deployment.installing.nix-services.system-d

Here are detailed steps for Ubuntu 22.04:

  1. Copy file .service to /etc/systemd/system: sudo cp openrims.service /etc/systemd/system
  2. Edit file .service and change Username and Execstart path.
  3. Start the service: systemctl enable openrims.service
  4. Change Owner of the java application to your user: sudo chmod a+rwx /home/ubuntu/applications/pharmadex2/pharmadex2-0.0.1.jar OR sudo cdmod 500 pharmadex2-0.0.1.jar

For reference here is a sample service file:

[Unit]

Description=Pharmadex 2 UAT version (madagascar)

After=pharmadex.service

[Service]

User=ubuntu

ExecStart=/home/{username}/applications/openrims/pharmadex2-0.0.1.jar

SuccessExitStatus=143

[Install]

WantedBy=multi-user.target

For Windows

The official guide is here https://docs.spring.io/spring-boot/docs/current/reference/html/deployment.html#deployment.installing.windows-services

Provide access from the Internet

To provide access from the Internet it will be a good idea to establish a proxy gateway like Nginx or Apache2.

The example of virtual server configuration for Apache 2 is in the binary distributive folder named “Linux” on GitHub.

For Ubuntu 22.04 and Apache2 here are the steps:

  1. Copy pharmadex.conf to apache folder e.g. /etc/apache2/sites-available
  2. Enable the site a2ensite pharmadex

Here is another sample Apache conf file with https enabled by Letsencrypt:

<VirtualHost *:80>

ServerName openrims.yourdomain.com

Redirect permanent / https://openrims.yourdomain.com/

</VirtualHost>


<VirtualHost *:443>

ServerName openrims.yourdomain.com

SSLEngine On

SSLCertificateFile C:\Certbot\live\openrims.yourdomain.com\fullchain.pem

SSLCertificateKeyFile C:\Certbot\live\openrims.yourdomain.com\privkey.pem

SSLProtocol         all -SSLv3 -TLSv1 -TLSv1.1

SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256

SSLHonorCipherOrder on

SSLCompression      off

SSLSessionTickets   off

SSLSessionCacheTimeout  300

ProxyPreserveHost On

<Location />

ProxyPass http://192.168.1.10:8084/

ProxyPassReverse http://192.168.1.10:8084/

</Location>

</VirtualHost>"

Configuring Google Authentication

LINK: See OpenRIMS - Installation Part 2

Special Configuration

LINK: See IIS as a gateway for Spring Boot application

[1] For current, available only to MSH staff

Retrieved from "http://129.151.190.5/index.php?title=OpenRIMS-RPM_-_Installation_Part_1&oldid=184"