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 rewrite

sudo systemctl restart apache2

Oracle OCI specific:

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

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

sudo iptables -I INPUT -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

Make a choice:

For ARM64 use

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

For x32_64 use

curl -SL -o dotnet.tar.gz https://download.visualstudio.microsoft.com/download/pr/91f66f75-bd3e-48f1-acb9-99c0da753f96/42c47999ee4c4d108774536afe5da160/aspnetcore-runtime-6.0.33-linux-x64.tar.gz

Then run:

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

Now download the required files from the OpenRIMS website:

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

sudo wget  https://www.openrims.org/wp-content/uploads/2024/08/openrims-pv.20240618.3.0.0.0.beta_.bf_.zip

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 OpenRIMS.PV.Main.API.dll

Edit appsettings.json connection string to MySQL with password:

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

A good appsettings.json file 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 OpenRIMS.PV.Main.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 openrimspv.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!