OpenRIMS-PVM - Installation Chapter 1

This guide describes the deployment for a MySQL Linux server i.e. Ubuntu for the below instructions.

Please click this link for an MSSQL deployment.

Pre-Requisites

You need a server to install on. Local or Cloud.

In this example we are deploying on an Oracle OCI server.

The server is accessed using SSH.

Basic Web Server Setup

sudo apt update

sudo apt install apache2

Then enable Proxy which will be used for the .Net api:

a2enmod proxy proxy_http proxy_html

sudo systemctl restart apache2

Oracle OCI specific:

sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 80 -j ACCEPT

sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 443 -j ACCEPT

sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 3306 -j ACCEPT

sudo netfilter-persistent save

Basic MySQL Setup

sudo apt install mysql-server

sudo mysql

Configure root user password:

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

Create database user named openrimspvm with your password of choice:

CREATE USER 'openrimspvm'@'%' IDENTIFIED BY 'password';

Give the user access to the database with the name you have chosen/defined (in appsettings.json - see later section):

GRANT PRIVILEGE ON pvims TO 'openrimspvm'@'%';

Or full access to database (only if remote access is disabled for better security):

GRANT ALL PRIVILEGES ON *.* TO 'sammy'@'localhost' WITH GRANT OPTION;

FLUSH PRIVILEGES;

.NET Core 6 Runtime

curl -SL -o dotnet.tar.gz https://download.visualstudio.microsoft.com/download/pr/33c6e1e3-e81f-44e8-9de8-91934fba3c94/9105f95a9e37cda6bd0c33651be2b90a/dotnet-sdk-6.0.201-linux-arm64.tar.gz

sudo mkdir -p /usr/share/dotnet

sudo tar -zxf dotnet.tar.gz -C /usr/share/dotnet

sudo ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet

APP and API

Please send an email to info@openrims.org to download the required files.

TIP - Install Midnight Commander for easy file navigation in the Linux commandline: sudo apt install mc (Install midnight commander for file management and permissions)

wget zip files for each app and api (from openrims.org/GitHub)

Unzip to /var/www/html/app using mc

Unzip to /var/www/html/api using mc

Make dll application file in the API folder executable:

sudo chmod -x PViMS.API.dll

Edit appsettings.json connection string to MySQL with password:

sudo nano /var/www/html/api/appsettings.json

A good connection string looks like this:

"ConnectionString": "Server=localhost,3306;Database=openrims-pv;User Id=pvuser; Password=P@55w0rd;Pooling=False;"

Test API with direct dotnet command:

dotnet PViMS.API.dll

Check for red text errors in the CLI window e.g. wrong database connection
Check that the database has been created in MySQL

Stop dotnet with Ctrl+C

Configure the Service

We need auto start in case of reboot

cd /etc/systemd/system

sudo nano openrimspvm.service

The system file must contain something like:

[Unit]
Description=Example .NET Web API App OpenRIMS-PVM running on Linux

[Service]
WorkingDirectory=/var/www/html/api
ExecStart=/usr/bin/dotnet /var/www/html/api/PViMS.API.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-example
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload

sudo systemctl start openrimspvm.service

sudo systemctl restart apache2

Secure The Website

We need to separate secure vhost: One for APP and one for API

Vhost on port 80 for redirect to APP

Vhost on 443 pointing to APP (Then API as <Location /> with reverse proxy?)

Vhost on port 80 for redirect API

This one is a reverse proxy to port 5000 where Kestrel is running the dotnet PViMS.API.dll

sudo nano /etc/apache2/sites-enabled/000-default.conf

Sample content with app and api:

ServerName subdomain.openrims.org

Redirect permanent / https://subdomain.openrims.org/

ErrorLog ${APACHE_LOG_DIR}/error.log

CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

ServerName subdomain-api.openrims.org

Redirect permanent / https://subdomain-api.openrims.org/

ErrorLog ${APACHE_LOG_DIR}/error.log

CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Then apply SSL:

sudo apt install certbot python3-certbot-apache

sudo certbot

Post SSL Configuration

sudo nano /etc/apache2/sites-enabled/000-default-le-ssl.conf

SAMPLE Apache .conf file:

<IfModule mod_ssl.c>
<VirtualHost *:443>
   ServerName pv.openrims.org
   DocumentRoot /var/www/html/app
   ErrorLog ${APACHE_LOG_DIR}/error.log
   CustomLog ${APACHE_LOG_DIR}/access.log combined
Include /etc/letsencrypt/options-ssl-apache.conf
SSLCertificateFile /etc/letsencrypt/live/pv-api.openrims.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/pv-api.openrims.org/privkey.pem
<Directory /var/www/html/app>
RewriteEngine on
# Don't rewrite files or directories
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
# Rewrite everything else to index.html to allow HTML5 state links
RewriteRule ^ index.html [L]
</Directory>
</VirtualHost>
</IfModule>
<IfModule mod_ssl.c>

<VirtualHost *:443>
   ServerName pv-api.openrims.org
   ErrorLog ${APACHE_LOG_DIR}/error.log
   CustomLog ${APACHE_LOG_DIR}/access.log combined
   <Location />
ProxyPreserveHost On
ProxyPass http://0.0.0.0:5000/
ProxyPassReverse http://0.0.0.0:5000/
</Location>
Include /etc/letsencrypt/options-ssl-apache.conf
SSLCertificateFile /etc/letsencrypt/live/pv-api.openrims.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/pv-api.openrims.org/privkey.pem
</VirtualHost>
</IfModule>

This Concludes the guide!