0. Prerequisite

To install openIMIS using Docker, you first need first to install Docker on your computer/server. Please visit https://docs.docker.com/get-docker/ website to download and install the version that matches your OS.

1. Download openIMIS Docker files

Download the files from openimis-dist_dkr onto your machine and extract the files.

Open

Figure 1: Download zip of the openIMIS dist_dkr repository

• Copy the downloaded .zip file to a new folder.

• Extract the files (On Windows: Right-Click on the .zip file and select from the popup Extract All)

• Within the extracted folder, make a copy and rename these files:

  • from .env.example to .env

  • from .env.openSearch.example to .env.openSearch

Note: For any other files in the archive that have a .example in the name, we recommend you create a copy with .example suffixes removed.

2. Edit the configuration files

Though the .env file has comments explaining each configurations, a few key configurations are highlighted below for your convenience.

Open the .env file with preferred editor and make the following updates:

• Set your SECRET_KEY to a secured key you can remember.

• Version Variables: The Version Variable determines which version of openIMIS you prefer to run in Docker. This version is by default set to the latest openIMIS release.

• Demo Data Variable: The Demo Data Variable if set to true as shown below, will start the openIMIS platform with already existing datasets. Unhash the variable assignment and set your preferred Boolean (true or false). true is only advised if you intend to explore the product, otherwise, set it to false.

Load Already Existing Data

Start With Empty Database

Please note that for every assignment there is no space before or after the =.

Not these:

But this:

Save the updated file and move to the next step

We highly recommend you read through the .env files before editing any other configuration options available.

3. Run the Docker containers via docker-compose

After editing the configuration files, you now open the Docker desktop and make sure it is running.

• Locate and copy the folder path of the extracted .zip file (where .env and .env.openSearch are).

• Open your preferred Command Line Interface (CLI): Terminal, Command Prompt or PowerShell.

For Command Prompt or Terminal

For Powershell

• Run the Docker containers via CLI

Once this completes successfully, you should have a complete openIMIS release running locally and accessible via your local network interface. By default the containers bind to port 80 and 443. You should be able to test it by navigating to http://localhost/front or https://localhost/front/login

Open

3.1. Administering the platform

If you configured the platform to include the DEMO_DATASET, you will automatically have a user account generated with the following credentials

4. Verify and Review the Running Services

The openIMIS Docker setup consists of several containers, each serving a specific role in the system:

• db: PostgreSQL database used to persist application data.

• backend: Django-based API server handling business logic and data processing.

• frontend: React-based user interface of openIMIS.

• migrations: Initializes or upgrades the backend database schema (runs once at startup).

• worker: Celery service for background processing and asynchronous tasks.

• rabbitmq: Message broker used by Celery for task queueing.

• opensearch: Search and analytics engine for indexing and querying openIMIS data.

• opensearch-dashboards: UI dashboard to visualize and explore data from OpenSearch.

• proxy/traefik (external network): Acts as a reverse proxy, routing HTTP/S traffic to the appropriate services.

All services communicate over a shared Docker network (openimis-net) and are initialized through the Docker Compose setup.

If the new initialization method works reliably, note that demo/static data (e.g., reference values, sample claims, insurees) will be automatically loaded via Django fixtures as part of the container initialization.

4.1. Verifying Running Containers

To check whether your Docker containers are running properly, you can use the following command:

Look for your openIMIS containers in the output. In the STATUS column, you should see messages like:

or

4.2. Health Checks

In addition to being "up", many openIMIS services include a Docker health check to ensure the container is fully operational (not just running). For example:

• The database container (db) uses pg_isready to confirm that PostgreSQL is accepting connections.

• The backend (backend, worker) containers depend on successful completion of the migrations container and may not start until it's marked healthy.

• The opensearch service uses an HTTP-based check to validate cluster health.

You should wait until the containers report Up ... (healthy) before assuming the service is ready to use.

To inspect container health details directly, you can run:

Or view logs with:

This is especially useful during initial setup or when troubleshooting startup issues.

4.3. Managing the running services

From within openimis-dist_dkr directory:

• To stop all docker containers: docker compose stop 

• To (re-)start all docker containers: docker compose up -d

• To pull new images or images update `docker compose pull`

4.4. Updating the Docker Images

To ensure you're using the latest available versions of the openIMIS components, you can pull updated images from the GitHub Container Registry:

This will download the latest images based on the tag specified in your .env file (e.g., develop, latest, or a specific release version).

4.5. Configure https via certbot

there is a docker-compose that support let’s encrypt certificates

first export NEW_OPENIMIS_HOST ,

dry run

actual setup

5. OpenSearch / OpenSearch Dashboards Setup

OpenSearch and OpenSearch Dashboards provide powerful search and analytics capabilities within the openIMIS platform. However, they are not enabled by default in the Dockerized openIMIS distribution and require additional setup steps.

IMPORTANT: Before starting, ensure that your openIMIS Docker setup is working with the database, backend, and frontend containers.

5.1. Step-by-Step Setup

1. Copy the example OpenSearch environment file and configure it. Edit .env.openSearch to adjust settings such as OPENSEARCH_PASSWORD, CLUSTER_NAME, and port numbers as needed for your environment.

2. Build Required Containers

Use the following command to build the additional containers (OpenSearch, Dashboards):

3. Run the Services

Once built, you can start the services. These will start OpenSearch, the Dashboards interface, and the proxy layer:

5.2. Integration with openIMIS Frontend and Backend

To fully integrate OpenSearch with openIMIS, a few environment variables need to be configured:

1. Set OpenSearch Authentication Token

In the main .env file of your openimis-dist_dkr setup, add:

Replace <base64_encoded_admin:password> with the base64-encoded version of your OpenSearch admin credentials.

2. Enable Proxy Route in openIMIS Frontend

In the Dockerfile or environment configuration of the openimis-fe_js container, set the following variable:

This defines the base path under which the OpenSearch Dashboards UI will be accessible.

3. Final Step: Run openIMIS Stack with OpenSearch

Once all the above steps are done, you can start or restart the main services with:

This will run the full openIMIS stack (DB, backend, frontend) including OpenSearch and Dashboards.

5.3. Accessing OpenSearch Dashboards

After everything is up and running, you can access the Dashboards UI at:

You should see the OpenSearch Dashboards interface, with access governed by the admin credentials you've set in .env.openSearch.

5.4. Using Sentry / Glitchtip

In order to use Sentry for frontend, you need to add the following environment variables to your `.env` file:

• REACT_APP_SENTRY_DSN