Get BAO Analytics Platform Running in Minutes with Docker

A step-by-step guide to getting the BAO Analytics Platform up and running with Docker Compose in no time.

Introduction

The BAO Analytics Platform (AP) is an open-source solution designed to help governments and development organizations ingest, merge, and explore data from multiple sources in real time. It features a powerful data warehouse, a data pipeline, identity management, and a built-in data visualization layer powered by Apache Superset.

While BAO AP can be deployed in various ways — cloud-hosted, hybrid, or on-premise — deploying it using Docker Compose is by far the easiest and most reproducible approach. In this guide, you’ll set up the full BAO Analytics Platform stack on your own server in just a few steps.

By the end of this post, you’ll have a fully functional BAO Analytics Platform running locally or on your server.

Server Hosting / System Requirements

Virtual machine or physical server Linux operating system, Ubuntu 24.04 LTS recommended 32 GB RAM 8 CPU, ideally 16 or 32 CPU 500 GB SSD storage

Prerequisites

Before getting started, make sure you have the following:

• Docker version > 28.4.0
• Docker Compose version > 2.39.4
• A Linux-based server or local machine (Ubuntu recommended)
• Sufficient system resources (minimum 16GB, recommended 32GB of RAM)

To verify your Docker version:

docker --version
docker compose version

Architecture Overview

The BAO Analytics Platform Docker setup includes the following components:

Postgres: Database for data-pipeline, identity, and Superset metadata Pulsar: Message broker for the data-pipeline service ClickHouse: Data warehouse for pipeline and Superset Redis: Caching for identity, data-pipeline, and Superset Superset: Data visualization and exploration tool Data Pipeline: Data ingestion and transformation (AP core component) Identity: User management and authentication (AP core component) Gateway: API gateway for the Analytics Platform DHIS2 Superset Gateway: Connects DHIS2 to Superset Proxy (NGINX): Reverse proxy for the entire platform

Setting up BAO Analytics Platform

Step 1 — Clone the official GitHub repository

Head on to https://github.com/hisptz/bao-ap-docker, click the green button “<> Code” and copy the HTTPS URL shown as below:

Open command prompt or terminal enter the command:

git clone https://github.com/hisptz/bao-ap-docker.git

Now you should be able to see the repo cloned using the following command:

ls

As shown in the following screenshot

Step 2— Pull Required Docker Images

Navigate inside the folder:

cd bao-ap-docker/analytics-platform/

Enter the following command to pull all the required images before starting the services:

docker compose pull 

This may take a few minutes depending on your internet speed and once all the required images are successfully pulled you will be able to see the following output on the terminal.

Step 3 — Proceed with Default Configuration

For this tutorial, let’s proceed with all default configuration to up and run the analytics platform.

In case if there is any permission issues refer the “Set Up Volume Permissions” section.

If you wish to change the default configurations and credentials head to the section “Configure the Services”

Edit the clickhouse config

Temporarily edit the clickhouse users config to setup without any passwords:

nano clickhouse/config/users.xml

Replace the entire content with:

<clickhouse>
    <users>
        <default>
            <no_password/>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
            <show_named_collections>1</show_named_collections>
            <show_named_collections_secrets>1</show_named_collections_secrets>
            <min_os_cpu_wait_time_ratio_to_throw>3</min_os_cpu_wait_time_ratio_to_throw>
            <profile>default</profile>
            <networks>
                <ip>::/0</ip>
            </networks>
        </default>
    </users>
</clickhouse>

Step 4— Start the Services

Enter the following command to start all the services:

docker compose up -d

Once all services started, you should be able to see the following output on the terminal:

Note: The pulsor-init is a temporary container for initializing the configurations. That will be exitted once the process is done.

Ideally when you run the following command the only exitted container should be “pulsor-init” the rest should be up and running.

docker compose ps -a

Voila.. Almost there.

Step 5— Post Setup: Initialization

Superset requires a one-time initialization when run for the first time.

Run database migration:

docker compose exec superset superset db upgrade

Initialize the superset application:

docker compose exec superset superset init

Create an admin superuser:

docker compose exec superset superset fab create-admin

Follow the prompts to set your admin username, email, and password.

Step 6— Configure Clients in the Analytics Platform

When configuring a client in the Analytics Platform interface, use these ClickHouse data warehouse configurations.

Access the Analytics Platform interface using public ip address or localhost if running locally.

http://public-ip-address/

Enter the default credentials as follows: Username: administrator Password: Admin_1234

Click the option “Clients” listed inside the menu icon on the top right corner.

On the Clients page, select the Admin.

Select “ANALYTICS PLATFORM CONFIG” and click the button “Add config”

The default configurations as follows (remember to change them accordingly if you have made any changes in the configuration) and save:

Provider: Local — ClickHouse Identity (Key): na Credential (Secret): na Container: bao-ap-client-main HostName: clickhouse Database: baoanalytics Username: bao Password: analytics-platform

Now, click the “Test connection” button under Blob store configuration. You should be able to see a popup stating “Blob store connection is valid”

Then, under Data warehouse configuration click the button “Initialize data warehouse”. You should see a success message as above.

That’s it.. Now you have successfully configure your Analytics Platform and ready to accept data from different sources as below.

Set Up Volume Permissions

Some services need write access to their mounted volumes. Run the following commands to configure the correct permissions.

For the Data Pipeline service:

sudo chown -R 1001:1001 data/analytics-platform && sudo chmod -R 755 data/analytics-platform

For the Pulsar service:

sudo chown -R 10000:10000 data/pulsar && sudo chmod -R 755 data/pulsar

Configure the Services

Todo

Troubleshooting

All the issues encountered when personally setting up BAO Analytics Platform are listed here with the solution. In case if you encounter anything different comment on this post, will incorporate them as well.

T1 — Unable to initialize the data warehouse under Data warehouse configurations

When you see any failure message stating the database does not exists, then manually create the database using the following command.

sudo docker exec -it analytics-platform-clickhouse-1 clickhouse-client - user bao - password analytics-platform - query "CREATE DATABASE IF NOT EXISTS baoanalytics"

References

[embed]Analytics Platform Combine disparate data sources with turnkey connectors. Unlock insights from data with natural text and advanced data…ap.baosystems.com

[embed]Deployment - Analytics Platform Official documentation for Analytics Platform for DHIS2docs.ap.baosystems.com