Page Comparison

We have seen in the previous section that Docker packaging is managing all components of the modular openIMIS. If you wish to install the modular openIMIS without Docker, you will have to install separately the backend, the frontend and the gateway (and other optional modules)

Installing openIMIS directly is a tradeoff: it is more complex to get running, has more components to update and monitor but it is also much more flexible for low-bandwidth environments where downloading large docker images is an issue.

TO DO

This guide is still missing:

configuration of the images folder
REST API configuration

Database

This guide does not cover the database setup. Both PostgreSQL and Microsoft SQL Server are supported here.

Minimal Linux setup

This takes Ubuntu as example but can easily be adapted to most other distributions.

Code Block
mkdir oi cd oi sudo apt install openssh-server curl sudo apt install git python3-venv python3-wheel libpq-dev python3-dev gcc g++ make

If you are going to use the Microsoft database, install the corresponding driver:

https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server?view=sql-server-ver16#17

Here is the version for Ubuntu until 2021:

Code Block

if ! [[ "16.04 18.04 20.04 21.04 21.10" == *"$(lsb_release -rs)"* ]];
then
    echo "Ubuntu $(lsb_release -rs) is not currently supported.";
    exit;
fi

sudo su
curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -

curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list > /etc/apt/sources.list.d/mssql-release.list

exit
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17
# optional: for bcp and sqlcmd
sudo ACCEPT_EULA=Y apt-get install -y mssql-tools
echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc
source ~/.bashrc
# optional: for unixODBC development headers
sudo apt-get install -y unixodbc-dev

Now, let’s create a Python virtual environment. This is not mandatory but strongly advised to avoid interactions between Python applications:

Code Block

...

cd ~/oi  # if you are not in this folder anymore
python3 -mvenv venv
source venv/bin/activate

Fetching and installing openIMIS apps

We will fetch the main application components, frontend and backend:

Code Block
git clone https://github.com/openimis/openimis-be_py.git git clone https://github.com/openimis/openimis-fe_js.git

Configure the backend

Code Block

cd openimis-be_py
# if you are not going to work from the main branch (latest release): git checkout develop
# You might need here to adapt the requirements.txt file. If pandas fails to install below, change to pandas==1.4.2

Adapt openimis.json to suit your needs of openIMIS modules to deploy.

Code Block
pip install -r requirements.txt python modules-requirements.py > modules-requirements.txt pip install -r modules-requirements.txt

Now, you will need to create a .env file with the main parameters of the backend:

Code Block

DB_HOST=mssql-host-server
DB_PORT=1433
DB_NAME=database-name
DB_USER=database-user
DB_PASSWORD=database-password
DB_ENGINE=mssql

INSUREE_NUMBER_LENGTH=10
INSUREE_NUMBER_MODULE_ROOT=7
SITE_ROOT=api
MASTER_PASS=')(#$1HsD'

Now, we just need to generate the static files:

Code Block
cd openIMIS ./manage.py collectstatic

Then, try to run the backend server:

Code Block
cd ~/oi/openimis-be_py/openIMIS # If not already there from last step ./manage.py runserver

If the server takes a really long time to start, the database connection parameters are probably wrong and it is waiting for a database timeout to print an error.

Configure the automated restart

For systemd, create a file /lib/systemd/system/openimis.service:

Code Block

[Unit]
Description=openIMIS backend
After=network-online.target

[Service]
WorkingDirectory=/home/openimis/oi/openimis-be_py/openIMIS/
ExecStart=/home/openimis/oi/venv/bin/python manage.py runserver
Restart=always
RestartSec=15s
KillMode=process
TimeoutSec=infinity
User=openimis
Group=openimis

[Install]
WantedBy=multi-user.target

Be careful to adapt the two /home/openimis and User/Group if your username is not openimis.

Start the server manually:

Code Block
sudo systemctl start openimis.service

To make it start automatically at boot:

Code Block
sudo systemctl enable openimis.service

If the service fails to start, check the logs with:

Code Block
sudo journalctl -u openimis.service

Configure the frontend

First step is to install node.js. OpenIMIS versions 1.2 to 1.5 are using node 16. The node installation instructions are https://github.com/nodesource/distributions/blob/master/README.md#deb but a generic solution like nvm is also a good option.

For Ubuntu with stock Node:

Code Block
curl -fsSL https://deb.nodesource.com/setup_16.x \| sudo -E bash - sudo apt-get install -y nodejs

Then, install yarn:

Code Block

curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update && sudo apt-get install yarn

Go the frontend folder:

Code Block
cd ~/oi/openimis-fe_js

You can now edit the openimis.json for the frontend to select the components to install.

When done, load the configuration:

Code Block
yarn load-config yarn install yarn build yarn global add serve

If building yarn fails with an out of memory error, use export GENERATE_SOURCEMAP=false

At this stage, you should be able to run the app in dev mode with yarn start. This is not recommended for production !!

So let’s build a static bundle and deploy it in nginx’s path:

Code Block
yarn build # If not already done above sudo mkdir /var/www/html/front/ sudo chown $USER /var/www/html/front/ cp -r build/* /var/www/html/front/

Configure nginx (gateway/reverse proxy)

The docker-compose version uses an openresty image that only relays, here we will be deploying a regular nginx pointing to the static site.

Nginx will also be handling the TLS (HTTPS) with Letsencrypt.

Code Block

language	bash

sudo apt install nginx
sudo rm /etc/nginx/sites-enabled/default  # remove the default site (it’s just a link, don’t worry)
sudo vi /etc/nginx/conf.d/openimis.conf

Here is a sample configuration, to be tuned to your setup. The SSL parts are commented out, they will be updated by Letsencrypt’s certbot:

Code Block

upstream docker-backend {
        server localhost:8000;
}
upstream docker-frontend {
        server localhost:3000;
}
upstream restapi {
        server localhost:8080;
}
server {
        server_name example.openimis.org;
#        return 301 https://$host$request_uri;
#}
#server {
#
#        listen       443 ssl;
#        server_name example.openimis.org;
#
##        ssl_certificate /etc/ssl/certs/example.openimis.org.crt;
##        ssl_certificate_key /etc/ssl/private/example.openimis.org.key;


        location /.well-known {
                root /var/www/html;
        }

        location /LegacyHome {
                return 204;
        }

        location /keepLegacyAlive {
                return 204;
        }

        location / {
        return 301 /front/;
        }

        location /home {
                return 301 /front/;
        }

        location /Home.aspx {
                return 301 /front/;
        }

        location ~/front/(.*) {
        root /var/www/html;
        error_page 404 $scheme://$host/front/;
        }


        location /iapi/ {
                proxy_pass http://docker-backend/api/;
                proxy_set_header   Host $host;
                proxy_set_header   X-Real-IP $remote_addr;
                proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header   X-Forwarded-Host $server_name;
        }

        location /api/ {
                proxy_pass http://docker-backend/api/;
                proxy_set_header   Host $host;
                proxy_set_header   X-Real-IP $remote_addr;
                proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header   X-Forwarded-Host $server_name;
        }

        location /rest/ {
                proxy_pass http://restapi/;
                proxy_set_header   Host $host;
                proxy_set_header   X-Real-IP $remote_addr;
                proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header   X-Forwarded-Proto https;
                proxy_set_header   X-Forwarded-Host $server_name;
        }
}

Now, restart nginx:

Code Block
sudo systemctl restart nginx.service

Finally, enable TLS/SSL with Letsencrypt:

Code Block
sudo apt-get install python3-certbot-nginx sudo certbot --nginx -d example.openimis.org

Install the mobile REST API

For the moment, the REST API is the last part of the openIMIS system that was not adapted to Postgres. It can be installed on Linux or other systems via Docker. This guide will show how to set it up as a stand-alone docker.

The REST API requires a Microsoft database!

Page Tree

root	@self

Previous step: MO1.1 Install the modular openIMIS using Docker

Table of content

Next step:

Versions Compared

Old Version 2

New Version 3

Key

TO DO

Database

Minimal Linux setup

Fetching and installing openIMIS apps

Configure the backend

Configure the automated restart

Configure the frontend

Configure nginx (gateway/reverse proxy)

Install the mobile REST API