{"id":26898359,"url":"https://github.com/mikeintoshsystems/dhis2heat","last_synced_at":"2026-04-28T08:33:04.209Z","repository":{"id":284622442,"uuid":"955491961","full_name":"MIKEINTOSHSYSTEMS/DHIS2HEAT","owner":"MIKEINTOSHSYSTEMS","description":"A Comprehensive data management and Health Equity Assessment and Analysis platform that fetches data from DHIS2, optimize, calculate, clean and visualize inequality data.","archived":false,"fork":false,"pushed_at":"2025-03-26T19:56:37.000Z","size":2,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T20:47:46.815Z","etag":null,"topics":["analytics","data","data-science","dhis2","equality","equity","health","heat","inequality","r","shiny","shinydashboard","visualization"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MIKEINTOSHSYSTEMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-26T18:12:00.000Z","updated_at":"2025-03-26T19:56:41.000Z","dependencies_parsed_at":"2025-03-26T20:47:52.324Z","dependency_job_id":"c350adb8-961d-4ab9-9173-b91d2eff37a2","html_url":"https://github.com/MIKEINTOSHSYSTEMS/DHIS2HEAT","commit_stats":null,"previous_names":["mikeintoshsystems/dhis2heat"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIKEINTOSHSYSTEMS%2FDHIS2HEAT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIKEINTOSHSYSTEMS%2FDHIS2HEAT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIKEINTOSHSYSTEMS%2FDHIS2HEAT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIKEINTOSHSYSTEMS%2FDHIS2HEAT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MIKEINTOSHSYSTEMS","download_url":"https://codeload.github.com/MIKEINTOSHSYSTEMS/DHIS2HEAT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246591810,"owners_count":20801985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","data","data-science","dhis2","equality","equity","health","heat","inequality","r","shiny","shinydashboard","visualization"],"created_at":"2025-04-01T05:46:41.049Z","updated_at":"2026-04-28T08:33:04.199Z","avatar_url":"https://github.com/MIKEINTOSHSYSTEMS.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DHIS2 HEAT+ Data Fetcher and Visualization Dashboard\r\n\r\n![Feature Screenshot](./app/www/assets/feature1.jpeg)\r\n\r\n## Table of Contents\r\n\r\n1. [Overview](#overview)\r\n2. [Technology Stack](#technology-stack)\r\n3. [Prerequisites](#prerequisites)\r\n4. [Repository Structure](#repository-structure)\r\n5. [Deployment Guide](#deployment-guide)\r\n   - [Host Server Setup](#host-server-setup)\r\n   - [Container Deployment](#container-deployment)\r\n   - [SSL Configuration](#ssl-configuration)\r\n6. [Application Architecture](#application-architecture)\r\n7. [Usage Guide](#usage-guide)\r\n8. [Troubleshooting](#troubleshooting)\r\n9. [Maintenance](#maintenance)\r\n\r\n## Overview\r\n\r\nThe DHIS2 HEAT+ Dashboard is a comprehensive data visualization and analysis platform designed to fetch, process, and visualize health equity data from DHIS2 systems. The application provides:\r\n\r\n- Secure authentication and user management\r\n- Data fetching from DHIS2 instances\r\n- Interactive visualizations including charts, maps, and tables\r\n- Data cleaning and transformation tools\r\n- Export capabilities to multiple formats\r\n\r\nThe system is containerized using Docker for easy deployment and scalability.\r\n\r\n## Technology Stack\r\n\r\n```mermaid\r\ngraph TD\r\n    A[Client Browser] --\u003e B[LiteSpeed/Web Server]\r\n    B --\u003e C[NGINX Proxy]\r\n    C --\u003e D[Shiny Application]\r\n    D --\u003e E[DHIS2 API]\r\n    D --\u003e F[(SQLite Database)]\r\n    \r\n    subgraph Host Server\r\n        B\r\n    end\r\n    \r\n    subgraph Docker Containers\r\n        C\r\n        D\r\n    end\r\n    \r\n    subgraph External Services\r\n        E\r\n    end\r\n```\r\n\r\n## Technology Stack Details\r\n\r\n### Frontend\r\n\r\n- **Shiny (R)**: Primary application framework\r\n- **HTML/CSS/JavaScript**: UI components and styling\r\n- **Plotly**: Interactive visualizations\r\n- **Leaflet/Mapbox**: Geographic visualizations\r\n\r\n### Frontend Layer\r\n\r\n```mermaid\r\ngraph LR\r\n    A[Shiny UI] --\u003e B[HTML/CSS]\r\n    A --\u003e C[JavaScript]\r\n    A --\u003e D[Shiny Widgets]\r\n    B --\u003e E[bslib Themes]\r\n    C --\u003e F[Plotly.js]\r\n    C --\u003e G[Leaflet/Mapbox]\r\n```\r\n\r\n### Backend\r\n\r\n- **R**: Data processing and analysis\r\n- **Shiny Server**: Application hosting\r\n- **NGINX**: Reverse proxy and SSL termination\r\n- **SQLite**: Local user database\r\n\r\n### Backend Layer\r\n\r\n```mermaid\r\ngraph LR\r\n    A[Shiny Server] --\u003e B[R Runtime]\r\n    B --\u003e C[httr API Calls]\r\n    B --\u003e D[dplyr Data Wrangling]\r\n    B --\u003e E[ggplot2 Visualizations]\r\n    B --\u003e F[RSQLite Database]\r\n    C --\u003e G[DHIS2 REST API]\r\n```\r\n\r\n### Infrastructure\r\n\r\n- **Docker**: Containerization\r\n- **Docker Compose**: Orchestration\r\n- **LiteSpeed Web Server**: Host web server (optional)\r\n\r\n### Infrastructure Layer\r\n\r\n```mermaid\r\ngraph TB\r\n    A[Docker Host] --\u003e B[Shiny Container]\r\n    A --\u003e C[NGINX Container]\r\n    B --\u003e D[Rocky Linux Base]\r\n    B --\u003e E[Shiny Server]\r\n    C --\u003e F[NGINX]\r\n    C --\u003e G[SSL Termination]\r\n    A --\u003e H[Host Web Server]\r\n```\r\n\r\n### Data Flow\r\n\r\n```mermaid\r\nsequenceDiagram\r\n    participant C as Client\r\n    participant L as LiteSpeed\r\n    participant N as NGINX\r\n    participant S as Shiny\r\n    participant D as DHIS2\r\n    \r\n    C-\u003e\u003eL: HTTPS Request\r\n    L-\u003e\u003eN: Proxy Pass\r\n    N-\u003e\u003eS: Forward Request\r\n    S-\u003e\u003eD: API Call\r\n    D--\u003e\u003eS: JSON Data\r\n    S--\u003e\u003eN: HTML Response\r\n    N--\u003e\u003eL: Proxy Return\r\n    L--\u003e\u003eC: Rendered Page\r\n```\r\n\r\n### Supporting Libraries\r\n\r\n- `shinydashboard`, `shinyWidgets`, `DT`, `httr`, `jsonlite`, `arrow`, `dplyr`, `ggplot2`\r\n\r\n## Prerequisites\r\n\r\n### Host Server Requirements\r\n\r\n- Linux server (Ubuntu 20.04/22.04 recommended)\r\n- Docker Engine (v20.10+)\r\n- Docker Compose (v2.0+)\r\n- Git\r\n- SSL certificates (Let's Encrypt recommended)\r\n- Minimum hardware:\r\n  - 4 CPU cores\r\n  - 8GB RAM\r\n  - 50GB disk space\r\n\r\n### Network Requirements\r\n\r\n- Ports 80, 443, 3939, 8939, 9443 open\r\n- Domain name with DNS configured\r\n\r\n## Repository Structure\r\n\r\n```\r\nDHIS2HEAT/\r\n├── app/                          # Shiny application\r\n│   ├── db/                       # SQLite database directory\r\n│   ├── dbackup/                  # Database backups\r\n│   ├── fetched_data/             # Cached DHIS2 data\r\n│   ├── module/                   # Shiny modules\r\n│   ├── saved_setting/            # Application settings\r\n│   ├── www/                      # Static assets\r\n│   ├── app.R                     # Main application file\r\n│   ├── server.R                  # Server logic\r\n│   ├── ui.R                      # UI components\r\n│   └── ...                       # Other R source files\r\n├── nginx_app/                    # NGINX configuration\r\n│   └── configuration/\r\n│       ├── certs/                # SSL certificates\r\n│       └── nginx/nginx.conf      # NGINX config\r\n├── .env                          # Environment variables\r\n├── docker-compose.yml            # Docker compose config\r\n├── Dockerfile.shiny              # Shiny container build\r\n├── init.deploy.sh                # Initial deployment script\r\n├── shiny-server.conf             # Shiny server config\r\n└── ...                           # Other configuration files\r\n```\r\n\r\n## Deployment Guide\r\n\r\n### Host Server Setup\r\n\r\n1. **Clone the repository**:\r\n\r\n   ```bash\r\n   git clone https://github.com/MIKEINTOSHSYSTEMS/DHIS2HEAT.git\r\n   cd DHIS2HEAT\r\n   ```\r\n\r\n2. **Set up SSL certificates**:\r\n\r\n   ```bash\r\n   mkdir -p nginx_app/configuration/certs\r\n   # Place your certs (fullchain.pem and privkey.pem) in the certs directory\r\n   ```\r\n\r\n3. **Configure environment variables**:\r\n   Edit the `.env` file with your DHIS2 credentials:\r\n\r\n   ```\r\n   DHIS2_BASE_URL=https://your.dhis2.instance\r\n   DHIS2_USERNAME=admin\r\n   DHIS2_PASSWORD=district\r\n   ```\r\n\r\n### Container Deployment\r\n\r\n1. **Build and start containers**:\r\n\r\n   ```bash\r\n   docker-compose -p dhis2heat up -d --build\r\n   ```\r\n\r\n2. **Verify containers are running**:\r\n\r\n   ```bash\r\n   docker-compose -p dhis2heat ps\r\n   ```\r\n\r\n3. **Initialize the application**:\r\n\r\n   ```bash\r\n   docker exec -it moheatpdhis2 /srv/shiny-server/init.deploy.sh\r\n   ```\r\n\r\n### SSL Configuration\r\n\r\n1. **Configure your web server** (LiteSpeed example shown in original config):\r\n   - Set up reverse proxy to forward traffic to NGINX (port 8939 for HTTP, 9443 for HTTPS)\r\n   - Configure SSL termination at both LiteSpeed and NGINX levels\r\n\r\n2. **Verify SSL**:\r\n\r\n   ```bash\r\n   curl -v https://heat.merqconsultancy.org:9443\r\n   ```\r\n\r\n## Application Architecture\r\n\r\n### Container Interconnectivity\r\n\r\n```mermaid\r\ngraph TD\r\n    A[Client] --\u003e B[LiteSpeed:443]\r\n    B --\u003e C[NGINX:9443]\r\n    C --\u003e D[Shiny:3939]\r\n    D --\u003e E[DHIS2 API]\r\n    D --\u003e F[SQLite Database]\r\n```\r\n\r\n1. **Client** accesses `https://heat.merqconsultancy.org`\r\n2. **LiteSpeed** handles SSL termination and forwards to NGINX\r\n3. **NGINX** proxies requests to Shiny Server\r\n4. **Shiny Server** serves the application and connects to:\r\n   - DHIS2 API for data fetching\r\n   - SQLite for user management\r\n\r\n### Port Mapping\r\n\r\n- 80: HTTP → 302 redirect to HTTPS\r\n- 443: HTTPS (LiteSpeed)\r\n- 3939: Shiny application port (internal)\r\n- 8939: NGINX HTTP port (internal)\r\n- 9443: NGINX HTTPS port (external)\r\n\r\n## Usage Guide\r\n\r\n### First-Time Setup\r\n\r\n1. Access the application at `https://yourdomain.com`\r\n2. Register an admin account (first user becomes admin)\r\n3. Configure DHIS2 connection in Settings → Fetcher Setting\r\n4. Save settings and fetch initial data\r\n\r\n### Key Features\r\n\r\n- **Data Preview**: View and filter fetched data\r\n- **Visualizations**: Interactive charts and maps\r\n- **Data Management**: Clean and transform datasets\r\n- **User Management**: Create and manage user accounts\r\n- **Export**: Download data in Excel or Parquet format\r\n\r\n### Common Commands\r\n\r\n**Restart services:**\r\n\r\n```bash\r\ndocker-compose -p dhis2heat restart\r\n```\r\n\r\n**View logs:**\r\n\r\n```bash\r\ndocker-compose -p dhis2heat logs -f\r\n```\r\n\r\n**Full cleanup:**\r\n\r\n```bash\r\ndocker-compose -p dhis2heat down --volumes --rmi all\r\n```\r\n\r\n**Update application:**\r\n\r\n```bash\r\ngit pull origin main\r\ndocker-compose -p dhis2heat up -d --build\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**1. SSL Errors**\r\n\r\n- Verify certificates are in `nginx_app/configuration/certs/`\r\n- Check permissions on certificate files\r\n- Ensure NGINX config points to correct cert paths\r\n\r\n**2. Connection Timeouts**\r\n\r\n- Verify DHIS2 credentials in `.env`\r\n- Check network connectivity to DHIS2 instance\r\n- Increase timeout values in NGINX config if needed\r\n\r\n**3. Blank Dashboard**\r\n\r\n- Check Shiny server logs: `docker logs moheatpdhis2`\r\n- Verify data was fetched successfully\r\n- Ensure required R packages are installed\r\n\r\n### Log Locations\r\n\r\n- Shiny Server: `docker logs moheatpdhis2`\r\n- NGINX: `docker logs moheatpdhis2proxy`\r\n- Application: `/srv/shiny-server/app/shiny_app_monitor.log`\r\n\r\n## Maintenance\r\n\r\n### Backup Procedures\r\n\r\n1. **Database backup**:\r\n\r\n   ```bash\r\n   docker exec moheatpdhis2 sqlite3 /srv/shiny-server/app/db/data.sqlite \".backup '/srv/shiny-server/app/dbackup/backup.sqlite'\"\r\n   ```\r\n\r\n2. **Data backup**:\r\n\r\n   ```bash\r\n   docker exec moheatpdhis2 tar czvf /srv/shiny-server/app/dbackup/data_$(date +%Y%m%d).tar.gz /srv/shiny-server/app/fetched_data/\r\n   ```\r\n\r\n### Update Procedure\r\n\r\n1. Pull latest changes:\r\n\r\n   ```bash\r\n   git pull origin main\r\n   ```\r\n\r\n2. Rebuild containers:\r\n\r\n   ```bash\r\n   docker-compose -p dhis2heat up -d --build\r\n   ```\r\n\r\n3. Restart services:\r\n\r\n   ```bash\r\n   docker-compose -p dhis2heat restart\r\n   ```\r\n\r\n### Monitoring\r\n\r\n- Set up monitoring for:\r\n  - Container health\r\n  - DHIS2 API response times\r\n  - Disk space for data storage\r\n  - Application logs for errors\r\n\r\n---\r\n\r\n![Feature Screenshot](./app/www/assets/app_loading.jpeg)\r\n\r\nThis documentation provides a comprehensive guide to deploying and maintaining the DHIS2 HEAT+ Dashboard. For additional support, please open an issue on the GitHub repository.\r\n\r\n\r\n---\r\n\r\n### Production Deployment\r\n\r\n```bash\r\n# Start\r\ndocker-compose --env-file .env -f prod.docker-compose.yml up -d\r\n\r\n# Stop\r\ndocker-compose --env-file .env -f prod.docker-compose.yml down --volumes --rmi all\r\n\r\n# Rebuild and restart\r\ndocker-compose --env-file .env -f prod.docker-compose.yml down \u0026\u0026 \\\r\ndocker-compose --env-file .env -f prod.docker-compose.yml up -d --build\r\n```\r\n\r\nAccess your app:\r\n\r\n- 🌐 **Shiny App:** [https://heat.merqconsultancy.org](https://heat.merqconsultancy.org)\r\n- 🧩 **SQLite Browser:** [https://your-server-ip:3001](https://your-server-ip:3001)\r\n\r\n---\r\n\r\n### SSL Configuration\r\n\r\nVerify SSL connection:\r\n\r\n```bash\r\ncurl -v https://heat.merqconsultancy.org:9443\r\n```\r\n\r\nCertificates should exist at:\r\n\r\n```\r\nnginx_app/configuration/certs/fullchain.pem\r\nnginx_app/configuration/certs/privkey.pem\r\n```\r\n\r\n---\r\n\r\n## Application Architecture\r\n\r\n```mermaid\r\ngraph TD\r\n    A[Client] --\u003e B[LiteSpeed:443]\r\n    B --\u003e C[NGINX:9443]\r\n    C --\u003e D[Shiny:3939]\r\n    D --\u003e E[DHIS2 API]\r\n    D --\u003e F[SQLite DB]\r\n```\r\n\r\n**Flow:**\r\n\r\n1. User connects via HTTPS to LiteSpeed\r\n2. LiteSpeed proxies to NGINX (9443)\r\n3. NGINX forwards to Shiny server (3939)\r\n4. Shiny interacts with SQLite + DHIS2 API\r\n\r\n---\r\n\r\n## Usage Guide\r\n\r\n### First-Time Setup\r\n\r\n1. Visit **[https://heat.merqconsultancy.org](https://heat.merqconsultancy.org)**\r\n2. Register the first admin user\r\n3. Go to **Settings → Fetcher Setting**\r\n4. Add DHIS2 credentials and test connection\r\n5. Fetch DHIS2 data → Start exploring visualizations!\r\n\r\n---\r\n\r\n### Common Commands\r\n\r\n```bash\r\n# Restart services\r\ndocker-compose --env-file .env -f prod.docker-compose.yml restart\r\n\r\n# View live logs\r\ndocker-compose --env-file .env -f prod.docker-compose.yml logs -f\r\n\r\n# Update app code\r\ngit pull origin main\r\ndocker-compose --env-file .env -f prod.docker-compose.yml up -d --build\r\n```\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\n| Issue                       | Likely Cause                      | Resolution                             |\r\n| --------------------------- | --------------------------------- | -------------------------------------- |\r\n| SSL not working             | Missing or invalid certs          | Verify `nginx_app/configuration/certs` |\r\n| Timeout fetching DHIS2 data | Invalid API credentials           | Update `.env` or fetcher settings      |\r\n| Blank dashboard             | Shiny crash or missing R packages | `docker logs moheatpdhis2`             |\r\n| SQLite locked               | Simultaneous writes               | Wait or restart app                    |\r\n\r\n**Logs:**\r\n\r\n```bash\r\ndocker logs moheatpdhis2          # Shiny\r\ndocker logs moheatpdhis2proxy     # NGINX\r\ndocker logs sqlitebrowser         # SQLite browser\r\n```\r\n\r\n---\r\n\r\n## Maintenance\r\n\r\n### Backup Database\r\n\r\n```bash\r\ndocker exec moheatpdhis2 sqlite3 /srv/shiny-server/app/db/data.sqlite \\\r\n\".backup '/srv/shiny-server/app/dbackup/backup.sqlite'\"\r\n```\r\n\r\n### Backup Data Cache\r\n\r\n```bash\r\ndocker exec moheatpdhis2 tar czvf /srv/shiny-server/app/dbackup/data_$(date +%Y%m%d).tar.gz \\\r\n/srv/shiny-server/app/fetched_data/\r\n```\r\n\r\n### System Monitoring\r\n\r\n- `docker ps` → container health\r\n- `docker stats` → CPU/memory usage\r\n- Disk space: `df -h /var/lib/docker`\r\n- Logs and alert checks (weekly)\r\n\r\n---\r\n\r\n![Feature Screenshot](./app/www/assets/app_loading.jpeg)\r\n\r\n**Maintained by:** MIKEINTOSH SYSTEMS | Michael Kifle Teferra\r\nFor support or issues, visit [GitHub Issues](https://github.com/MIKEINTOSHSYSTEMS/DHIS2HEAT/issues)\r\n\r\n---\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeintoshsystems%2Fdhis2heat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeintoshsystems%2Fdhis2heat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeintoshsystems%2Fdhis2heat/lists"}