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