0. Prerequisite

To install openIMIS using Docker, you first need first to install Docker on your computer/server. Please visit 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

After downloading, you will have to complete the next steps via the command-line from inside the folder you have just downloaded and extracted.

2. Edit the configuration files

The Docker based deployment of openIMIS is configured using environment variables. For convenience, these environment variables are managed in env files. You will find example configuration files from the archive you downloaded in Step 1.

Copy the example configuration files to new files and remove the .example suffix.
As an example, the .env.example should be copied or renamed to just .env

The files have comments explaining what the various configurations are for. We will highlight a few of them here.

Version variables: The following variables determine which version of openIMIS you will run in docker - by default they default to the latest release of the project.

Demo data variable: The DEMO_DATASET variable if enabled as shown below, will start the openIMIS platform with pre-populated sample data which you can use to explore the product. When it is False, the database will be empty.

We recommend reading through the .env files to understand the rest of the configuration options available.

3. Run the Docker containers via docker-compose

After editing the configuration files, you are now ready to run openIMIS.

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.