Deployment

Configuration

The deployment of OpenLMIS is based on docker-compose files. For each current instance, the deployment-related files reside in selv-v3-deployment repository. However, configuration files (like credentials or settings) can be found in the selv-v3-configuration repository. All Jenkins jobs are copying necessary files from the configuration repository in order to execute the deployment scripts later.

Auth Server credentials

If the database has been wiped out, or not yet initiated it's possible that the initial credentials for the auth server are not configured and the UI can't connect to the server properly (and the user receives HTTP code 401 when trying to log in). In order to fix that, values for both server and UI client in auth.oath_clent_details table should reflect the values from env file (settings.env or .env-restore). authorizedgranttypes column helps to establish if the credentials are for the server-side (client_credentials) or for the UI side (password).

Postgres extensions

If for some reason extensions specified in this file were not created properly - it might result in errors while executing the initial SQL migrations. In this case, the extensions should be created manually:

Upgrade

To incorporate new version of OpenLMIS into SELV v3, the following steps should be executed:

1. Backup the database

It’s always a good practice to begin the upgrade with a backup of all database instances, in case something goes wrong.

2. Update superset-patchup

As mentioned in the Superset Configuration page - check changes in the core version of this repository before every release. If necessary, changes from the OLMIS core should be ported to the selv-v3-superset-patchup repository. The superset-patchup package is used in selv-v3-distro/reporting/superset/Dockerfile.

3. Update UI repository

As source files from selv-v3-ui repository override source files from all core UI repositories, it’s necessary to track the changes made since last release. It’s possible that a particular file was removed/renamed in the core, and overriding it no longer takes any effect. Additionally, the logic, naming, etc. could change as well so each change has to be verified separately. There are two practices of overriding files that help with tracking what changes have been made to the file for SELV v3:

1. copy a file to override as a part first commit, and made all required changes as a second one

2. add comments around changed parts of code

Both are useful while comparing core and SELV v3 versions but it’s always good to take a quick look at a whole file, to be sure nothing is missed.

4. Update the versions of the services

Update the versions of the services for both shared self-v3-configuration versions file and selv-v3-distro .env file which is currently a separate source of versions for selv-v3-distro.

5. Verify the upgrade

After redeployment of an updated instance, it should be verified if all services are running correctly. Probably the easiest way is to enter the instance server via SSH and run docker-compose ps -a, and investigate if some of the services were shut down unintentionally. A common reason for a service down are migration errors in case there was some patchup-release incorporated for the implementation. You can verify what migrations were already run in the schema_version table (available in each schema). Usually, it’s done by executing them manually and then updating the table, but fix for this depends on what had gone wrong. After all, all migrations has to be executed, and this table has to contain a footprint of executing them.