Health Service

A health aggregator microservice that monitors the status and availability of all services in the containerized service ecosystem. Performs periodic health checks via HTTP, MySQL, and TCP protocols with automatic Docker/Podman service discovery.

Tech Stack

• Language: Python 3.12
• Framework: FastAPI
• Server: Uvicorn (2 workers)
• Async HTTP: aiohttp
• Async MySQL: aiomysql
• Container Discovery: Docker SDK (docker-py)

Project Structure

health/
├── app.py                # FastAPI app, background loop, API endpoints
├── checks.py             # Health check implementations (HTTP, MySQL, TCP)
├── discovery.py          # Docker/Podman auto-discovery engine
├── config.yaml           # Service configuration (auto-generated or manual)
├── requirements.txt      # Python dependencies
├── Dockerfile            # python:3.12-slim container
└── .github/workflows/
    └── build.yml         # CI/CD pipeline

Environment Variables

Core

Variable	Default	Description
HEALTH_CONFIG	config.yaml	Path to config file
AUTO_DISCOVER	1	Enable automatic service discovery
INTERVAL_SECONDS	60	Check interval (min: 5)
MAX_HISTORY	50	Max check results retained
LOG_LEVEL	INFO	Logging level

MySQL Defaults (for discovered services)

Variable	Default	Description
MYSQL_HEALTH_USER	health	Default MySQL health user
MYSQL_HEALTH_PASSWORD	CHANGEME	Default MySQL health password

Discovery

Variable	Default	Description
PREFERRED_NETWORK	—	Docker network for service IPs
DISCOVERY_ALLOW_CLI	1	Allow docker/podman CLI fallback
DOCKER_HOST	—	Custom Docker socket URL

CORS

Variable	Default	Description
CORS_ALLOW_ORIGINS	localhost:3000,...	Allowed origins
CORS_ALLOW_METHODS	*	Allowed HTTP methods
CORS_ALLOW_HEADERS	*	Allowed headers

Getting Started

Local

pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 5011 --reload

Docker

docker build -t health-aggregator .
docker run -d -p 5011:5011 \
  -v /run/podman/podman.sock:/run/podman/podman.sock \
  health-aggregator

Port: 5011

API Endpoints

Method	Endpoint	Description
GET	/healthz	Liveness probe
GET	/readyz	Readiness probe (checks if services loaded)
GET	/health/report	Latest aggregated health status
POST	/health/check-now	Trigger immediate health check
GET	/health/history	Historical check results (last N runs)
GET	/config.yaml	Current service configuration

Health Report Response

{
  "summary": { "total": 8, "healthy": 7, "unhealthy": 1 },
  "results": [
    { "name": "next-api", "type": "http", "ok": true, "status": 200, "latency_ms": 42.3 },
    { "name": "mysql", "type": "mysql", "ok": true, "latency_ms": 15.7 }
  ]
}

Service Discovery

The service auto-discovers containers via Docker/Podman with fallback to CLI. Services can be configured via:

1. Container labels: com.rj.health.url, com.rj.health.type
2. Built-in defaults for known services (mysql, minio, next-api, next-app, next-mail, etc.)
3. Manual config in config.yaml

Config File Format

interval_seconds: 60
services:
  - name: mysql
    type: mysql
    host: 172.17.0.2
    port: 3306
    user: health
    password: CHANGEME
    timeout_ms: 1200
  - name: next-api
    type: http
    url: http://172.18.0.5:5002/healthz
    timeout_ms: 1200

Built-in Service Defaults

Service	Port	Health Path
mysql	3306	TCP check
minio	9000	/minio/health/ready
next-api	5002	/healthz
next-app	3000	/api/healthz
next-mail	5007	/healthz
next-venmo	5006	/healthz
next-extractor	5010	/healthz
next-email	5008	/healthz
next-monitoring	5014	/api/healthz

CI/CD

GitHub Actions builds multi-arch Docker images (amd64/arm64) and pushes to GHCR on pushes to main/master and semantic version tags.