# Release process

## Host matrix

| Product | Toolchain | Hosts |
|---------|-----------|-------|
| **Server** | Bare standalone (`scripts/bare-standalone.cjs`) | **`linux-x64`**, **`linux-arm64` only** |
| **Client** | Electron Forge (`forge.config.cjs`) | `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64` |

Same layout as PearDock’s rolling pipeline, except PearData agents ship **Linux-only**.

## Installer

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

Script: [`scripts/install.sh`](../scripts/install.sh) · unit: [`deploy/peardata.service`](../deploy/peardata.service)

Server install (`--server`) writes systemd under `/opt/peardata`, enables **journal** Logs (`peardata` ∈ `systemd-journal`), and when **Docker** is detected enables container metrics/names (`peardata` ∈ `docker`, `PEARDATA_DOCKER=1`). See [GETTING-STARTED.md](./GETTING-STARTED.md) and [user-guide/containers.md](../user-guide/containers.md).

## Local builds

```bash
npm install

# Everything CI builds
npm run make

# Or separately
npm run make:server                 # both Linux arches
npm run make:server:linux-x64
npm run make:client                 # all client hosts
npm run make:client:darwin-arm64

# Dev Electron UI (not Pear runtime)
npm run start:client
```

Outputs land under `out/`:

```
out/peardata-server-linux-x64/peardata-server
out/peardata-linux-x64/peardata-client      # Electron (folder name = package.json name)
out/peardata-darwin-arm64/peardata.app      # macOS
```


Env knobs:

| Env | Default | Meaning |
|-----|---------|---------|
| `PEARDATA_SERVER_HOSTS` | `linux-x64,linux-arm64` | Server host list |
| `PEARDATA_CLIENT_HOSTS` | all 64-bit | Client host list |
| `PEARDATA_SKIP_CLIENT=1` | off | Server-only release |
| `PEARDATA_SKIP_REBUILD=1` | on in CI | Skip `@electron/rebuild` |
| `PEARDATA_SKIP_QVAC=1` | off | Tools-only Electron client (no Bare LLM worker). Also auto-set for `win32-arm64` (no QVAC prebuild). |
| `PEARDATA_CLIENT_TIMEOUT_MS` | `1200000` with QVAC / `600000` without | Per-host client package timeout |
| `DRY_RUN=1` | off | Stage archives, skip upload |

Desktop clients ship **QVAC** (`@qvac/sdk` + forge plugin) unless `PEARDATA_SKIP_QVAC=1`. See [QVAC.md](./QVAC.md) and [CI.md](./CI.md).

## CI / forge pipelines

| Forge | Workflow | Trigger | Output |
|-------|----------|---------|--------|
| **Gitea** | `.gitea/workflows/release-rolling.yml` | push `main`/`master` + manual | Build matrix → prerelease tag **`rolling`** |
| **GitHub** | `.github/workflows/release.yml` | `v*` tags + manual | Same matrix → GitHub Release assets |
| Both | `.gitea/workflows/ci.yml` / `.github/workflows/ci.yml` | PR / push | Unit tests |

Rolling script: [`scripts/gitea-rolling-release.sh`](../scripts/gitea-rolling-release.sh)  
Orchestrator: [`scripts/make.cjs`](../scripts/make.cjs)  
Hosts: [`scripts/hosts.cjs`](../scripts/hosts.cjs)

### Secrets

| Secret | Used by |
|--------|---------|
| `RELEASE_TOKEN` | Gitea rolling publish (**required**) |
| `GITEA_URL` | Optional forge base URL |
| `GITHUB_TOKEN` | GitHub Release (automatic) |

### macOS codesign

Darwin **clients** built on Linux are seal-signed with vendored `tools/rcodesign/` (see that README). Avoids Gatekeeper “damaged” false positives. Not notarized unless you set Developer ID credentials.

## Version & tag (semver)

```bash
# 1. Bump version in package.json
# 2. Commit + tag
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin main
git push origin vX.Y.Z
```

- **Gitea:** every `main` push republishes `rolling` (latest main binaries).
- **GitHub:** `v*` tags upload versioned archives from the release workflow.

## Source-only tarball (optional)

```bash
bash scripts/release.sh   # dist/peardata-vX.Y.Z.tar.gz (source tree)
```

Prefer the binary matrix for operators.

## Changelog guidance

1. **Protocol** — RPC / push changes  
2. **Security** — auth / roles  
3. **Desktop** — Electron / Pear UI  
4. **Ops** — env, systemd, collectors  
5. **Breaking** — re-dial / invite requirements  

## Related

- [CI.md](./CI.md)
- [TECH-CHOICES.md](./TECH-CHOICES.md) (Bare import maps)
- PearDock reference: `docs/RELEASE.md` in the peardock repo