peardata/docs/RELEASE.md

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

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

Script: scripts/install.sh · unit: 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 and user-guide/containers.md.

Local builds

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 and 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
Orchestrator: scripts/make.cjs
Hosts: 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)

# 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 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
• TECH-CHOICES.md (Bare import maps)
• PearDock reference: docs/RELEASE.md in the peardock repo