MO2.2 Install openIMIS without using Docker

1 General comments about the installation procedure
- 1.1 TO DO
- 1.2 Database
2 1 - Minimal Linux setup
3 2 - Fetching and installing openIMIS apps
4 3 - Install the mobile REST API
- 4.1 3.1 - Setting up the REST API
- 4.2 3.2 - Making sure the REST API is working

General comments about the installation procedure

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

Database

This guide does not cover the database setup. Both PostgreSQL and Microsoft SQL Server are supported here, unless the REST API is needed.

1 - Minimal Linux setup

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

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:

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:

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

2 - Fetching and installing openIMIS apps

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

2.1 - Configure the backend

2.1.1 - Backend requirements installation

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

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

Now, we just need to generate the static files:

Then, try to run the backend server:

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.

2.1.2 - Configure the automated restart

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

Be careful to adapt the 4 occurences of the “openimis” if your username is different:

two /home/openimis
User/Group

Start the server manually:

To make it start automatically at boot:

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

2.2 - Configure the frontend

2.2.1 - node & yarn installation

The first step is to install node.js. openIMIS versions 1.2 to 1.5 are using node 16. The node installation instructions are available here, but a generic solution like nvm is also a good option.

For Ubuntu with stock Node:

Then, install yarn:

2.2.2 - Frontend requirements installation

Go the frontend folder:

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

When done, load the configuration:

At this stage, you should be able to run the app in dev mode with yarn start.

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

2.3 - 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.

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:

Now, restart nginx:

Finally, enable TLS/SSL with Letsencrypt:

You will then need to choose whether or not to redirect HTTP traffic to HTTPS:

3 - Install the mobile REST API

At 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.

3.1 - Setting up the REST API

First, go to oi and clone the REST API repository:

At this stage, you should be on the main branch.

Before starting the REST API, you will need to edit the docker-compose and Dockerfile files with the database information.

Here is a sample docker-compose file. Replace the 5 database values in the environment section:

Here is a sample Dockerfile file. Replace the 5 ENV database values:

Then, you can start the Docker service:

3.2 - Making sure the REST API is working

Once the container has finished building and has started, you can check that the REST API is properly working:

First, you can type docker ps. In the STATUS column, you should see something similar to Up xx minutes.
Then you can access the REST API and see if you see any data fetched from the database, for instance by accessing the following page: <your-openIMIS-URL>/rest/api/claim/Controls

Previous step: MO2.1 Install openIMIS using Docker

Table of content

Next step:

openIMIS