Skip to content

README.md

Latest commit

 

History

History
166 lines (131 loc) · 5.62 KB

README.md

File metadata and controls

166 lines (131 loc) · 5.62 KB
Raw

MODO（墨斗）

CI License: MIT

MODO is a configurable multi-cloud telemetry dashboard built with Cloudflare Workers, Hono, FastAPI, Prometheus node exporters, and Oracle MySQL HeatWave. It collects infrastructure metrics, exposes a private API gateway, and renders a six-panel operational dashboard.

The repository contains reference configuration only. It does not include a hosted service, production node inventory, database, or Cloudflare account.

Architecture

Browser
   │ HTTPS
   ▼
Cloudflare Worker / Hono
   │ authenticated private proxy
   ▼
FastAPI gateway ───────► Oracle MySQL HeatWave
   ▲                           │
   │ Prometheus scrape         └─ optional HeatWave AutoML
   │
Configured node_exporter fleet

The backend is intended to remain private. The Worker injects a shared internal secret when proxying API requests. Database and node endpoints should not be exposed directly to the public Internet.

Features

  • Concurrent node_exporter metric collection with CPU counter warm-up.
  • HeatWave-backed telemetry, analytics views, retention, and optional AutoML.
  • Aggregated dashboard API to avoid high-frequency fan-out polling.
  • ECharts fleet, resource, latency, inventory, and diagnostic views.
  • Optional Supabase authentication and realtime updates.
  • Cloudflare Worker proxy with masked upstream errors and scheduled retention.
  • Bounded API rate limiting with trusted Worker client-IP forwarding.
  • CI checks for Python tests, TypeScript, Wrangler packaging, and the 400-line first-party source limit.

Repository layout

modo/
├── data-bridge/
│   ├── config/nodes.json.example
│   ├── src/                    # ingestion, FastAPI modules, schema and AutoML
│   └── tests/
├── edge-app/
│   ├── src/client/             # browser behavior modules
│   ├── src/fragments/          # dashboard HTML fragments
│   ├── src/index.ts            # Worker routes and page composition
│   └── wrangler.jsonc
├── deploy/                     # reference systemd and Tunnel templates
├── docs/
│   ├── deployment/
│   ├── issues/
│   └── security/
├── scripts/
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

First-party source files are limited to 400 physical lines. Generated files and vendored dependencies are excluded. CI enforces the rule with scripts/check_source_file_lines.py.

Requirements

  • Python 3.13.15
  • Node.js 26.10.0
  • pnpm 12.6.0
  • Cloudflare account for deployment
  • Oracle MySQL HeatWave for database-backed runtime features
  • node_exporter on each monitored node

MySQL, HeatWave, and Docker are not required to run the repository's unit tests.

Backend development

From the repository root:

cp .env.example .env
cp data-bridge/config/nodes.json.example data-bridge/config/nodes.json

python3 -m venv data-bridge/venv
source data-bridge/venv/bin/activate
pip install --require-hashes -r data-bridge/requirements.lock
cd data-bridge
pytest -v tests/

Replace all example values before starting services. The documentation IP addresses are non-routable examples.

To run against an Oracle MySQL HeatWave environment you control, follow the HeatWave deployment notes. Do not run schema initialization against production without a backup and maintenance plan.

Edge development

cd edge-app
cp .dev.vars.example .dev.vars
pnpm install --frozen-lockfile
pnpm dev

Set API_BACKEND_URL and use the same INTERNAL_API_SECRET as the backend. Supabase values may remain empty when authentication and realtime features are not being exercised.

Useful checks:

pnpm build:css
pnpm run cf-typegen
pnpm run typecheck
pnpm exec wrangler deploy --dry-run

pnpm deploy performs a real Cloudflare deployment and should only be used with an explicitly authorized account and environment.

Configuration and generated files

  • .env, .dev.vars, and data-bridge/config/nodes.json are local and ignored.
  • edge-app/src/tailwind.generated.css is generated by pnpm build:css.
  • edge-app/worker-configuration.d.ts is generated by Wrangler.
  • TOPOLOGY_HUB_NODE selects the dashboard aggregation node; when unset, the first configured node is used.
  • Automatic model retraining is disabled in the example configuration and must be explicitly enabled.

Documentation

License

MODO is licensed under the MIT License.

Public data boundary

The Worker exposes read-only monitoring data anonymously. Frontend login does not restrict these APIs. Node summaries expose only name, region, provider and map coordinates; telemetry responses use an explicit public field allowlist and omit host addresses. Use non-sensitive node names and approximate public coordinates. Keep database credentials and real node configuration outside Git.

Python dependencies are installed from data-bridge/requirements.lock with hashes. To update intentionally, run uv pip compile requirements.txt --python-version 3.13.15 --generate-hashes --output-file requirements.lock inside data-bridge.