How openlmis/openlmis-ref-distro works
Project Type and Purpose
• This is a full‑stack, containerized reference distribution for OpenLMIS v3+.
• It uses Docker Compose to assemble a suite of microservices (the core OpenLMIS Services), a UI layer (reference UI modules), infrastructure pieces (configuration container, syslog container, database), and an optional reporting pipeline (Debezium, NiFi, Superset, cron jobs).
• It also includes extensions/integrations (DHIS2, stock‑management validators, one‑network extensions).
File‑Structure Analysis
• Top‑level:
• .env, docker-compose.yml, start/stop scripts → orchestrator of the entire stack
• config/ → configuration container definition (Dockerfile + mounted volumes)
• dhis2/ → optional DHIS2 integration stack (with its own docker‑compose)
• reporting/ → reporting subsystem (Debezium Connect, NiFi, Superset, reporting DB, cron jobs + Compose files)
• docs/ → Sphinx‑based architecture and component documentation
• utils/ → assorted helper containerized tools (awscli, browsermob‑proxy, bzt‑yarn, etc.)
• Notice multiple Compose override files for different extensions and data‑load modes.
README Insights
• Describes how the Docker Compose files are the “authoritative” assembly of services.
• Explains the configuration container pattern via a named volume (service‑config).
• Describes the logging container (log) capturing syslog from services.
• Outlines how to load demo data, performance data, and refresh profiles.
• Details optional components: DHIS2, extensions, reporting pipeline.
Main Components
a. Core Services Cluster
• ReferenceData, StockManagement, Requisition, Fulfillment, Notification, Report, Auth, CCE, etc.
• These expose REST APIs.
b. API Gateway / Reverse Proxy
• Nginx + consul‑template container → routes HTTP traffic from browser to UI modules and services.
c. UI Modules
• Reference UI front‑end modules (served via Nginx, static assets).
d. Configuration Container
• config image providing /config volume to all services.
e. Database Layer
• Postgres container for core services
• Separate Postgres (or other) for reporting, initialized by SQL scripts.
f. Logging
• Syslog container collecting logs from services via Docker logging or rsyslog.
g. Reporting Pipeline
• Debezium Connect (captures CDC from core DB)
• Apache NiFi (ingests, transforms, loads into reporting DB)
• Reporting DB container
• Superset container (visualization/dashboard)
• Cron job container (periodic queries or MV refreshes)
h. Integrations / Extensions
• DHIS2 stack (own DB, config, Compose file)
• One‑network, OpenLMIS extensions (separate Compose overlays)
i. Utility Containers (optional)
• AWS CLI, Browsermob Proxy, bzt-yarn, snapshot tools, ERD generator, etc.
Relationships & Data Flows
• Browser → Nginx → UI Modules → Core Microservices (HTTP REST)
• Core Microservices ↔ Core DB (JDBC over private Docker network)
• All services mount service‑config volume from Config container at /config
• All services send logs → Syslog container (rsyslog over network)
• Debezium Connect → reads from Core DB → publishes change events to Kafka topic
• NiFi → subscribes to Kafka → processes data → writes to Reporting DB
• Superset → reads from Reporting DB → serves dashboards to browser
• Cron jobs → run periodic SQL or REST calls → update materialized views or reports
Architectural Patterns & Principles
• Microservices communicating over REST
• Externalized configuration via a dedicated config container + volume
• Centralized logging with a syslog container
• Change‑Data‑Capture for reporting (Debezium + NiFi)
• Docker Compose as the deployment descriptor (infrastructure as code)
• Overlay Compose files for feature toggles (demo data, performance data, extensions)