peardata/docs/GETTING-STARTED.md

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):

curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash

Non-interactive:

# 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:

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

cd peardata
npm install
cp .env.example .env   # optional

Run the agent (source)

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

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.

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:

PEARDATA_SWARM=1 npm run start:server

See STORAGE-HYPERDB.md.

Mint an invite

npm run mint-invite -- operator
# → pd1.…

Share the invite string. Recipients paste it into the desktop connect box.

Run the desktop

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 (--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):

# 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 — Charts, Metric Correlations, Logs, Fleet, Alerts
• REST-API.md
• ARCHITECTURE.md
• ROADMAP.md
• CONFIGURATION.md