snxraven/peardata
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Updates
CI / test (push) Successful in 57s
Details
Release rolling / release (push) Successful in 4m45s
Details

Browse Source
This commit is contained in:
Raven Scott
2026-07-18 16:41:09 -04:00
parent f7e26d1aac
commit d56c6757a5
24 changed files with 9935 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CI.md
+57 -58
View File
@@ -1,81 +1,80 @@
# CI & pipelines
## GitHub Actions
PearData mirrors the PearDock-style **cross-compile from one Linux runner** pipeline: Bare servers + Electron clients, published as rolling / tagged releases.
| Workflow | Trigger | Jobs |
|----------|---------|------|
| `.github/workflows/ci.yml` | push / PR / manual | **test** (Node 20 + 22 matrix), **lint-docs** |
| `.github/workflows/release.yml` | `v*` tags / manual | install, test (`SKIP_INTEGRATION=1`), pack tarball + sha256, GitHub Release |
## Host matrix
### CI job details (`ci.yml`)
**test**
- `actions/checkout@v4` + `setup-node` matrix `20` / `22`
- HTTPS rewrite for GitHub git deps
- `npm install --no-audit --no-fund`
- `npm test` (integration enabled by default)
- `node --check` on key entrypoints: `server/server.js`, `client/connection.js`, `app.js`, `shared/crypto-auth.js`
- `NODE_OPTIONS=--dns-result-order=ipv4first`
**lint-docs**
- Asserts required documentation files exist (README, architecture, protocol, data model, REST API, roadmap, tech choices, getting started, security, desktop, configuration, LICENSE, etc.)
### Release job details (`release.yml`)
- Node 22
- `SKIP_INTEGRATION=1 npm test` (avoids flaky UDP on some runners)
- Source tarball under `dist/`
- Upload via `softprops/action-gh-release` when ref is a tag
| Product | Hosts |
|---------|-------|
| Server (Bare) | `linux-x64`, `linux-arm64` **only** |
| Client (Electron) | `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64` |
## Gitea Actions
| Workflow | Trigger | Job |
|----------|---------|-----|
| `.gitea/workflows/ci.yml` | push / PR / manual | install, `npm test`, `node scripts/healthcheck.js` (liveness) |
| `.gitea/workflows/release-rolling.yml` | **every** push to `main`/`master` + manual | test, `scripts/gitea-rolling-release.sh` → Gitea `rolling` prerelease |
| `.gitea/workflows/ci.yml` | push / PR / manual | install, `npm test` |
| `.gitea/workflows/release-rolling.yml` | **every** push to `main`/`master` + manual | test → build matrix → Gitea tag **`rolling`** |
Mirrors patterns from peardock-class forge pipelines (IPv4-first DNS, HTTPS rewrite for GitHub deps, always-on rolling release).
Rolling job (ubuntu-latest, ~180m timeout):
1. System deps for Electron packaging
2. `npm ci --ignore-scripts` + esbuild install
3. `SKIP_INTEGRATION=1 npm test`
4. Install vendored `tools/rcodesign` (darwin client seal-sign)
5. `scripts/gitea-rolling-release.sh`
- `make.cjs server` → `peardata-server-*.tar.gz`
- `make.cjs client` → `peardata-client-*.tar.gz`
- upload to `rolling` prerelease
Manual inputs: `skip_client`, `server_hosts`, `client_hosts`, `dry_run`.
**Secret:** `RELEASE_TOKEN` (required to publish). Optional `GITEA_URL`.
## GitHub Actions
| Workflow | Trigger | Jobs |
|----------|---------|------|
| `.github/workflows/ci.yml` | push / PR / manual | **test** (Node 20+22), **lint-docs** |
| `.github/workflows/release.yml` | `v*` tags / manual | Same binary matrix → GitHub Release assets |
## Local parity
```bash
npm install
npm test
node --check server/server.js
node --check client/connection.js
node --check app.js
node --check shared/crypto-auth.js
bash scripts/release.sh
SKIP_INTEGRATION=1 npm test
# Server (Linux Bare)
npm run make:server:linux-x64
# Client (Electron)
npm run make:client:linux-x64
# Full matrix (slow)
npm run make
# Stage release archives without upload
DRY_RUN=1 bash scripts/gitea-rolling-release.sh
```
## Key scripts
| Script | Role |
|--------|------|
| `scripts/hosts.cjs` | Host lists (`SERVER_LINUX`, `ALL_64`) |
| `scripts/make.cjs` | Orchestrate server/client builds |
| `scripts/bare-standalone.cjs` | Pack Bare `peardata-server` |
| `scripts/build-client-bundle.cjs` | esbuild GUI → `electron/app.bundle.cjs` |
| `scripts/predownload-electron.cjs` | Pre-fetch Electron zips for CI |
| `scripts/sign-macos-app.cjs` | Darwin client codesign |
| `scripts/gitea-rolling-release.sh` | Build + stage + Gitea upload |
| `forge.config.cjs` | Electron Forge packaging |
## Integration tests in CI
Integration spins a real HyperDHT listener. If a runner blocks UDP/DHT:
```yaml
env:
SKIP_INTEGRATION: '1'
```
Unit tests (`crypto-auth`, `protocol`, `acl`) always run. See [TESTING.md](./TESTING.md).
## Secrets (forge)
| Secret | Used by |
|--------|---------|
| `GITHUB_TOKEN` | GitHub Release (automatic) |
| `RELEASE_TOKEN` | Gitea rolling release (**required** for publish) |
| `GITEA_URL` | Forge base URL (optional; defaults to runner `GITHUB_SERVER_URL`) |
Do not store `SERVER_SEED` in CI unless a dedicated deploy workflow needs it.
## Required docs check
When adding documentation, update the `lint-docs` step in `.github/workflows/ci.yml` so the file is asserted present.
Release workflows set `SKIP_INTEGRATION=1`. Unit CI may run integration when the runner allows DHT/UDP. See [TESTING.md](./TESTING.md).
## Related
- [RELEASE.md](./RELEASE.md)
- [TESTING.md](./TESTING.md)
- [TECH-CHOICES.md](./TECH-CHOICES.md) — Bare import maps
docs/RELEASE.md
+81 -82
View File
@@ -1,106 +1,105 @@
# Release process
## Preconditions
## Host matrix
- [ ] `npm test` passes (use `SKIP_INTEGRATION=1` only if the runner cannot do DHT)
- [ ] Version bumped in `package.json`
- [ ] Docs updated if protocol / env / UX changed
- [ ] No secrets in the tree (`.env`, `data/`, identity files)
- [ ] `git status` clean except intended changes
| 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` |
## Version & tag
Same layout as PearDock’s rolling pipeline, except PearData agents ship **Linux-only**.
## Local builds
```bash
# 1. Bump version in package.json (semver)
# 2. Commit
git add package.json
git commit -m "Release vX.Y.Z"
npm install
# 3. Tag
# 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
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` |
| `DRY_RUN=1` | off | Stage archives, skip upload |
## 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"
# 4. Push
git push origin main
git push origin vX.Y.Z
```
Tag pattern **`v*`** triggers versioned GitHub releases. On Gitea, **every push to `main`/`master`** rebuilds the rolling release:
- **Gitea:** every `main` push republishes `rolling` (latest main binaries).
- **GitHub:** `v*` tags upload versioned archives from the release workflow.
| Forge | Workflow | Trigger | Output |
|-------|----------|---------|--------|
| GitHub | `.github/workflows/release.yml` | `v*` tags / manual | Source tarball + sha256 → GitHub Release |
| Gitea | `.gitea/workflows/release-rolling.yml` | push to `main`/`master` / manual | `scripts/gitea-rolling-release.sh` → prerelease tag **`rolling`** |
The rolling job always runs after a successful install+test on the default branch. It deletes and recreates the `rolling` tag/release so operators can always download the latest main build.
## Local artifacts
## Source-only tarball (optional)
```bash
bash scripts/release.sh
bash scripts/release.sh # dist/peardata-vX.Y.Z.tar.gz (source tree)
```
Produces:
```
dist/
├── peardata-vX.Y.Z.tar.gz
├── peardata-vX.Y.Z.tar.gz.sha256
└── RELEASE_NOTES.md
```
Verify:
```bash
cd dist
sha256sum -c peardata-vX.Y.Z.tar.gz.sha256
# or: shasum -a 256 -c …
```
Tarball **excludes** `node_modules/`, `.git/`, `data/`, `dist/`.
## What ships
| Included | Not included |
|----------|--------------|
| Source (server, client, shared, UI) | `node_modules` |
| CI workflows | `.env` / secrets |
| Docs + systemd unit | Runtime `data/` |
| Scripts | Generated release dist |
Consumers install with `npm install` after unpacking.
Prefer the binary matrix for operators.
## Changelog guidance
For each release note:
1. **Protocol** — method / push / version bumps
2. **Security** — auth or default role changes
3. **Desktop** — pear-ctrl / window / Pear dependency bumps
4. **Ops** — env vars, systemd, healthcheck
5. **Breaking** — call out re-dial / re-invite requirements
## Hotfix without retag
Push commits to `main` for CI only. Prefer a new patch tag for anything operators must download.
## Rollback
- **App code**: redeploy previous tag tarball / checkout
- **Server seed**: only if compromised — generate new seed (new public key); re-issue all invites; clients must dial the new key
- **Peer policy**: restore `data/peer-policy.json` from backup if revoke tables were corrupted
## Secrets for forges
| Secret | Where | Purpose |
|--------|-------|---------|
| `GITHUB_TOKEN` | GitHub (automatic) | Upload release assets |
| `RELEASE_TOKEN` | Gitea (**required**) | Publish/update `rolling` release |
| `GITEA_URL` | Gitea (optional) | Forge API base (defaults from runner) |
Never put `SERVER_SEED` in CI secrets unless a dedicated deploy job needs it — prefer generating seeds on the target host.
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)
- [SECURITY.md](./SECURITY.md)
- [CONFIGURATION.md](./CONFIGURATION.md)
- [TECH-CHOICES.md](./TECH-CHOICES.md) (Bare import maps)
- PearDock reference: `docs/RELEASE.md` in the peardock repo