Deployment

HealthGuard supports two deployment methods:

• Docker Compose (recommended): One command to start PostgreSQL, Collector, and Dashboard.
• From Source: For local development or debugging.

Prerequisites

• Docker and Docker Compose
• (Source only) Node.js >= 20 and Yarn 1.22+

Option 1: Docker Compose (Recommended)

git clone https://github.com/Claud-Lu/healthguard.git
cd healthguard
docker compose up -d

Open http://localhost in your browser and register an account.

Default service ports:

Service	Port	Notes
Dashboard	80	Web UI
Collector	3100	Event ingestion API; health check at /health
PostgreSQL	5432	Data persistence

Environment Variables

Override defaults via a .env file or Docker Compose environment variables:

Variable	Description	Recommendation
DATABASE_URL	PostgreSQL connection string	Use a strong password in production
CORS_ORIGIN	Allowed CORS origin	Set to your real domain; avoid *
HEALTHGUARD_AGENT_TOKEN	Repair Agent bearer token	Generate a strong random secret
JWT_SECRET	Session signing secret	Must be changed in production

Production Checklist

1. Change the default database password: The default docker-compose.yml uses healthguard for development convenience.
2. Enable HTTPS: Use a reverse proxy (Nginx, Traefik, or Caddy) with a valid TLS certificate.
3. Restrict CORS: Replace CORS_ORIGIN=* with your actual Dashboard domain.
4. Back up PostgreSQL regularly: Use pg_dump or volume snapshots.

Option 2: Run from Source

git clone https://github.com/Claud-Lu/healthguard.git
cd healthguard
yarn install

# Start PostgreSQL (skip if you already have one locally)
docker run -d \
  -e POSTGRES_USER=healthguard \
  -e POSTGRES_PASSWORD=healthguard \
  -e POSTGRES_DB=healthguard \
  -p 5432:5432 \
  postgres:16

# Start all services (Collector + Dashboard + Demo)
yarn dev:local

Local URLs:

Service	URL
Dashboard	http://127.0.0.1:5175
Collector	http://127.0.0.1:3100/health
Demo	http://127.0.0.1:5174

Upgrade

cd healthguard
git pull
docker compose down
docker compose up -d --build

Verify the Deployment

1. Open the Dashboard and register an account.
2. Create an H5 or mini-program project and copy the appKey.
3. Integrate the SDK in a demo app and trigger an error.
4. Return to the Dashboard and confirm the event is aggregated into an Issue.