149 lines
5.6 KiB
Markdown
149 lines
5.6 KiB
Markdown
# PearData
|
|
|
|
**Decentralized, P2P, real-time monitoring for the Pear / Holepunch ecosystem.**
|
|
|
|
Each machine runs a lightweight **PearMonitor agent**. A Pear desktop client dials agents by public key and shows fleet + per-node live dashboards. Agents also expose an **agent-compatible REST API** (`/api/v1`, `/api/v2`, `/api/v3`) for scripts, Grafana, and Prometheus.
|
|
|
|
Built from the [pear-app-template](https://github.com/snxraven) HyperDHT + protomux-rpc patterns used by PearDock-class apps.
|
|
|
|
| Plane | Stack |
|
|
|-------|--------|
|
|
| Transport | **HyperDHT** secret streams (Noise) |
|
|
| RPC | **protomux-rpc** + compact-encoding JSON |
|
|
| Metrics | 1s collector → tiered buffers → push + query |
|
|
| AuthZ | Roles (`viewer` / `operator` / `admin`) + `pd1.` invites + admin seed |
|
|
| HTTP | agent-style REST on `127.0.0.1:18888` |
|
|
| Desktop | **Pear** (`pear-electron` + `pear-bridge` + `<pear-ctrl>`) |
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
### One-line installer (recommended)
|
|
|
|
```bash
|
|
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash
|
|
```
|
|
|
|
```bash
|
|
# Server only (Linux Bare + systemd → /opt/peardata)
|
|
# Enables journal Logs + Docker metrics/names when Docker is detected
|
|
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash -s -- --server --yes
|
|
|
|
# Desktop client only
|
|
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash -s -- --client --yes
|
|
```
|
|
|
|
### From source
|
|
|
|
```bash
|
|
cd peardata
|
|
npm install
|
|
|
|
# Terminal A — agent (prints public key + REST URL)
|
|
npm run start:server
|
|
|
|
# Terminal B — REST smoke test
|
|
curl -s http://127.0.0.1:18888/api/v3/info | jq
|
|
curl -s 'http://127.0.0.1:18888/api/v3/data?chart=system.cpu&after=-30&points=30' | jq
|
|
|
|
# Terminal C — mint an operator invite (optional)
|
|
npm run mint-invite -- operator
|
|
|
|
# Terminal D — Pear / Electron desktop
|
|
npm start
|
|
# or: npm run start:client
|
|
```
|
|
|
|
In the UI, paste the **agent public key** (viewer) or a **`pd1.` invite**.
|
|
Paste `SERVER_SEED` for admin without an invite.
|
|
|
|
```bash
|
|
npm test
|
|
npm run healthcheck
|
|
```
|
|
|
|
---
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
peardata/
|
|
├── app.js / index.html / ui/ # Pear fleet dashboard
|
|
├── shared/ # Protocol, metrics catalog, schema, crypto
|
|
├── spec/ # Generated Hyperschema + HyperDB definitions
|
|
├── scripts/build-db.js # Regenerate spec/ (`npm run build:db`)
|
|
├── server/ # PearMonitor agent
|
|
│ ├── server.js # DHT + HyperDB + pipeline + REST boot
|
|
│ ├── pipeline.js # collector → store → anomaly → push
|
|
│ ├── db/ # HyperDB model + Corestore + swarm replicate
|
|
│ ├── handlers/monitor.js # Domain RPCs
|
|
│ ├── services/ # collector, store, retention, warm-flush, anomaly, jobs
|
|
│ ├── rest/ # agent-compatible HTTP API
|
|
│ └── core/ rpc/ utils/ # Auth, ACL, sessions (template)
|
|
├── client/ # Multi-peer connection manager
|
|
├── user-guide/ # End-user desktop workflows
|
|
├── docs/ # Engineer / operator documentation
|
|
├── deploy/peardata.service # systemd (installer also writes journal/docker groups)
|
|
└── test/
|
|
```
|
|
|
|
---
|
|
|
|
## npm scripts
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `npm start` | Pear desktop UI |
|
|
| `npm run start:server` | PearMonitor agent (P2P + REST) |
|
|
| `npm run start:client` | Electron desktop (packaged UI) |
|
|
| `npm run make` | Build Linux servers + all client arches |
|
|
| `npm run make:server` | Bare `peardata-server` (`linux-x64` / `linux-arm64`) |
|
|
| `npm run make:client` | Electron clients (all 64-bit hosts) |
|
|
| `npm test` | brittle unit + integration |
|
|
| `npm run mint-invite -- [role]` | Offline `pd1.` invite |
|
|
| `npm run build:db` | Regenerate HyperDB `spec/` |
|
|
| `npm run healthcheck` | Liveness / remote ping |
|
|
| `npm run soak` | Load exercise |
|
|
|
|
---
|
|
|
|
## Auth model
|
|
|
|
| Mode | How | Role |
|
|
|------|-----|------|
|
|
| Viewer | Dial public key only | `viewer` (read + subscribe) |
|
|
| Capability | `pd1.` invite or HMAC token | granted role |
|
|
| Admin seed | HMAC proof from `SERVER_SEED` | `admin` |
|
|
| Allowlist | `PEARDATA_ADMIN_KEYS` | admin for listed peers |
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Doc | Contents |
|
|
|-----|----------|
|
|
| **[User guide](./user-guide/README.md)** | Desktop — Charts, Correlations, Logs, Containers, Fleet, Settings / Data Manager |
|
|
| [Getting started](./docs/GETTING-STARTED.md) | Install, agent, REST, desktop, systemd (journal + Docker) |
|
|
| [Docs index](./docs/README.md) | Full engineer / operator doc set |
|
|
| [Roadmap](./docs/ROADMAP.md) | MVP → advanced phases |
|
|
| [Architecture](./docs/ARCHITECTURE.md) | PearDock mapping, planes, modules |
|
|
| [Protocol](./docs/PROTOCOL.md) | RPC methods & pushes (incl. Data Manager) |
|
|
| [Data model](./docs/DATA-MODEL.md) | Metrics, anomalies, health, weights, logs, retention tiers |
|
|
| [REST API](./docs/REST-API.md) | `/api/v1\|v2\|v3` |
|
|
| [Dashboard](./docs/DASHBOARD.md) | Charts wall / Correlate / Containers naming |
|
|
| [Tech choices](./docs/TECH-CHOICES.md) | Collector, charts, Bare maps |
|
|
| [HyperDB storage](./docs/STORAGE-HYPERDB.md) | Warm history, peer links, swarm sync, prune |
|
|
| [Release](./docs/RELEASE.md) | Binary host matrix + rolling CI |
|
|
| [CI](./docs/CI.md) | Gitea / GitHub pipelines |
|
|
| [Security](./docs/SECURITY.md) | Threat model & hardening |
|
|
| [Configuration](./docs/CONFIGURATION.md) | Environment reference |
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
**AGPL-3.0-only** — see [LICENSE](./LICENSE).
|
|
|
|
PearData is released under the same license family as PearDock (GNU Affero General Public License v3).
|