158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
# Getting started
|
||
|
||
## Requirements
|
||
|
||
- **Installer path:** Linux (server) and/or Linux/macOS (desktop client); `curl` + `tar`
|
||
- **From source:** Node.js **≥ 20**; Pear runtime optional for `pear run`
|
||
- Linux recommended for full net/disk `/proc` collectors
|
||
|
||
## One-line installer (recommended)
|
||
|
||
Pulls **`rolling`** release binaries (same forge as PearDock-style installs):
|
||
|
||
```bash
|
||
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash
|
||
```
|
||
|
||
Non-interactive:
|
||
|
||
```bash
|
||
# Linux agent → /opt/peardata + peardata.service
|
||
curl -fsSL …/scripts/install.sh | bash -s -- --server --yes
|
||
|
||
# Desktop client
|
||
curl -fsSL …/scripts/install.sh | bash -s -- --client --yes
|
||
```
|
||
|
||
| Role | What you get |
|
||
|------|----------------|
|
||
| Server | Bare `peardata-server` in `/opt/peardata`, user `peardata`, systemd unit |
|
||
| Client | Electron app (`~/Applications/peardata.app` on macOS, `~/.local/share/peardata` on Linux) |
|
||
|
||
Overrides: `PEARDATA_GITEA_URL`, `PEARDATA_OWNER`, `PEARDATA_REPO`, `PEARDATA_TAG`, `PEARDATA_VERSION`, `PEARDATA_SERVER_DIR`, `PEARDATA_YES=1`.
|
||
|
||
After the server starts once:
|
||
|
||
```bash
|
||
sudo grep -E '^(SERVER_PUBLIC_KEY|SERVER_SEED)=' /opt/peardata/.env
|
||
curl -s http://127.0.0.1:18888/api/v3/info
|
||
```
|
||
|
||
## Install from source
|
||
|
||
```bash
|
||
cd peardata
|
||
npm install
|
||
cp .env.example .env # optional
|
||
```
|
||
|
||
## Run the agent (source)
|
||
|
||
```bash
|
||
npm run start:server
|
||
```
|
||
|
||
Banner shows:
|
||
|
||
- **publicKey** — dial this from the desktop (viewer)
|
||
- **rest** — e.g. `http://127.0.0.1:18888/api/v3/info`
|
||
- **admin** — use `SERVER_SEED` from `.env` or mint `pd1.` invites
|
||
|
||
Agent persists identity in `.env` on first boot.
|
||
|
||
### REST smoke tests
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:18888/api/v3/info
|
||
curl -s http://127.0.0.1:18888/api/v1/charts | head
|
||
curl -s 'http://127.0.0.1:18888/api/v3/data?chart=system.cpu&after=-60&points=60'
|
||
curl -s 'http://127.0.0.1:18888/api/v3/allmetrics?format=prometheus' | head
|
||
```
|
||
|
||
Disable REST: `PEARDATA_REST=0`.
|
||
|
||
### HyperDB (warm storage)
|
||
|
||
On by default. Agent banner shows `hyperdb:` public key.
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:18888/api/v3/db | jq
|
||
```
|
||
|
||
Warm history is written about once per minute (tier1). Linked-node Hyperswarm sync:
|
||
|
||
```bash
|
||
PEARDATA_SWARM=1 npm run start:server
|
||
```
|
||
|
||
See [STORAGE-HYPERDB.md](./STORAGE-HYPERDB.md).
|
||
|
||
## Mint an invite
|
||
|
||
```bash
|
||
npm run mint-invite -- operator
|
||
# → pd1.…
|
||
```
|
||
|
||
Share the invite string. Recipients paste it into the desktop connect box.
|
||
|
||
## Run the desktop
|
||
|
||
```bash
|
||
npm start
|
||
# pear run -d .
|
||
```
|
||
|
||
1. Paste agent public key or `pd1.` invite
|
||
2. Optional: paste `SERVER_SEED` for admin
|
||
3. Connect → live overview + charts
|
||
4. Admin: **Mint invite**
|
||
|
||
## systemd (Linux)
|
||
|
||
Prefer the [one-line installer](#one-line-installer-recommended) (`--server`). It installs the Bare binary, writes `peardata.service`, adds `peardata` to **`systemd-journal`**, and enables host journal for the Logs tab (`PEARDATA_JOURNAL=1`). When **Docker** is detected it also adds `peardata` to the **`docker`** group, sets `SupplementaryGroups=… docker`, and enables `PEARDATA_DOCKER=1` so charts show human names (e.g. `dozzle`) instead of hashes.
|
||
|
||
Manual (matches installer layout):
|
||
|
||
```bash
|
||
# After placing peardata-server + .env under /opt/peardata
|
||
sudo useradd --system --home /opt/peardata --shell /usr/sbin/nologin peardata # if needed
|
||
sudo usermod -aG systemd-journal peardata
|
||
# If Docker is installed:
|
||
sudo usermod -aG docker peardata
|
||
# In /opt/peardata/.env: PEARDATA_DOCKER=1 and PEARDATA_DOCKER_SOCKET=/var/run/docker.sock
|
||
# In the unit: SupplementaryGroups=systemd-journal docker
|
||
sudo cp deploy/peardata.service /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now peardata
|
||
journalctl -u peardata -f
|
||
```
|
||
|
||
From-source Node agents can still use `npm run start:server` under a custom unit; packaged releases use `/opt/peardata/peardata-server`.
|
||
|
||
## Roles cheat sheet
|
||
|
||
| Goal | Action |
|
||
|------|--------|
|
||
| Read-only monitoring | Dial pubkey only |
|
||
| Ack alerts / run jobs | `pd1.` operator invite |
|
||
| Mint invites / revoke | Admin seed or admin invite |
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Check |
|
||
|---------|-------|
|
||
| REST connection refused | Agent running? `PEARDATA_REST` not `0`? Port free? |
|
||
| Desktop can’t dial | Firewall / DHT; same machine should work; wait for punch |
|
||
| Empty net/disk charts | Non-Linux host — expected until platform collectors land |
|
||
| `PERMISSION_DENIED` | Need higher role invite or admin seed |
|
||
| Integration tests hang | `SKIP_INTEGRATION=1 npm test` on restricted networks |
|
||
|
||
## Next reading
|
||
|
||
- **[User guide](../user-guide/README.md)** — Charts, Metric Correlations, Logs, Fleet, Alerts
|
||
- [REST-API.md](./REST-API.md)
|
||
- [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||
- [ROADMAP.md](./ROADMAP.md)
|
||
- [CONFIGURATION.md](./CONFIGURATION.md)
|