MO2.2.1 Install openIMIS backend

In this section, we will provide the install guide for the modular openIMIS backend (API) as services in Windows or standalone applications in Linux. Please follow the appropriate setup based on your server configuration.

Download modular openIMIS backend

• Download and unzip the release from Github openimis-be_py into a new folder (e.g. C:\openIMIS\backend).

Install python and dependencies

• Install Python 3 (recommended in a virtualenv)

• Install pip

• Within openimis-be_py directory

  • install openIMIS (external) dependencies: 

    pip install -r requirements.txt

  • generate the openIMIS modules dependencies file (from openimis.json config; adapt the list of modules if necessary): 

    python script\modules-requirements.py openimis.json > modules-requirements.txt

  • install openIMIS current modules: 

    pip install -r modules-requirements.txt

  • Copy the example environment setup and adjust the settings (like database connection): cp .env.example .env. Refer to .env.example or the Environment Variable tables above for more info.

     

Configure the database connection

• By default, openIMIS is connected to PostgreSQL (django.db.backends.postgresql)

• The openIMIS has also possibility to connect using MSSQL Server (mssql):

  • via ODBC (and pyodbc) driver

  • using TCP/IP protocol (with server DNS name as hostname or localhost) and fixed port (leave DB_PORT here below empty for dynamic port)

  • SQL Server (not Windows/AD) authentication (user name password managed in SQL Server admin). Download and install the ODBC that corresponds to your OS and MS-SQL Server version (Microsoft ODBC Driver for SQL Server - ODBC Driver for SQL Server )

• Create an openimis-be_py/.env file to provide your database connection info:

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

• At this stage, you may (depends on the database you connect to) need to:

  • apply Django migrations, from openimis-be_py/openIMIS: 

    python manage.py migrate

  • create a superuser for Django admin console, from openimis-be_py/openIMIS: 

    python manage.py createsuperuser

Run the modular openIMIS backend locally

Start openIMIS from within openimis-be_py/openIMIS: python manage.py runserver

To edit (modify) an existing openIMIS module (e.g. openimis-be-claim)

• checkout the module's git repo NEXT TO (not within!) openimis-be_py directory and create a git branch for your changes

• from openimis-be_py

• uninstall the packaged module you want to work on (example: openimis-be-claim): pip uninstall openimis-be-claim

• install the 'local' version of the module: pip install -e ../openimis-be-claim_py/

• from here on, openIMIS is using the local content of the module (with live update)

To create a new openIMIS module (e.g. openimis-be-mymodule)

• create a (git-enabled) directory next to the other modules, with a subdirectory named as your module 'logical' name: /openimis-be-mymodule_py/mymodule

• from /openimis-be_py/openIMIS:

• create the module skeleton: python manage.py startapp mymodule ../../openimis-be-mymodule_py/mymodule

• prepare your module to be mounted via pip: create and complete the /openimis-be-mymodule_py/setup.py (and README.md,... files)

• every openIMIS module must provide its urlpatterns (even if empty):

• create the file /openimis-be-mymodule_py/mymodule/urls.py

• with content: urlpatterns = []

• register your module in the pip requirements of openIMIS, referencing your 'local' codebase: pip install -e ../../openimis-be-mymodule_py/

• register your module to openIMIS django site in /openimis-be_py/openimis.json

• from here on, your local openIMIS has a new module, directly loaded from your directory.

To manage translations of your module

• from your module root dir, execute '../openimis-be_py/script/gettext.sh' ... this extract all your translations keys from your code into your module root dir/locale/en/LC_MESSAGES/django.po

• you may want to provide translation in generated django.po file... or manage them via lokalize (need to upload the keys,...)

To run unit tests on a module (example openimis-be-claim)

• from openimis-be_py

• (re)initialize test database (at this stage structure is not managed by django):

• launch unit tests, with the 'keep database' option: python manage.py test --keep claim

To get profiler report (DEBUG mode only)

In request query include additional parameters:

• prof=True - get profiler report instead of standard response for given endpoint

• download=True - additionally changes report formatting to one acceptable by snakeviz

Example:

http://localhost:8000/api/graphql?prof=True&download=True creates profiler report for execution of query/mutation defined in request's POST body.

Run the modular openIMIS backend as a service