Add Bare standalone binaries and Gitea rolling release CI

Package peardock-server and peardock-client with bare-pack + bare-build --standalone (hello-pear-bare pattern), embedding the full module graph and native addons. Server uses bare-node-runtime imports plus Docker socket shims; client is a Bare agent with holesail control. Gitea Actions builds multi-host artifacts and publishes a rolling release via RELEASE_TOKEN.
2026-07-11 00:19:39 -04:00
parent fa99bd8c6e
commit 0e097308ce
21 changed files with 2920 additions and 69 deletions
@@ -1,6 +1,137 @@
 # peardock release process

-## Server tarball + checksums
+## Standalone Bare binaries (recommended)
+
+peardock ships **two separate self-contained binaries** built with the Holepunch
+stack (`bare-pack` + `bare-build --standalone`):
+
+| Binary | Role |
+|--------|------|
+| `peardock-server-<host>` | HyperDHT Docker control plane (dockerode over Unix socket) |
+| `peardock-client-<host>` | Bare agent: Holesail local control + optional headless HyperDHT connect |
+
+Each binary embeds the full JS module graph and native addons (no `node_modules`
+on the target host). Pattern matches [hello-pear-bare](https://github.com/holepunchto/hello-pear-bare)
+and [bare-build](https://github.com/holepunchto/bare-build).
+
+### Local build
+
+```bash
+npm ci
+# Native host (server + client)
+npm run make
+
+# Explicit targets
+npm run make:server:linux-x64
+npm run make:client:linux-x64
+npm run make:all   # all desktop hosts × both products
+```
+
+Outputs:
+
+```
+out/server/<host>/peardock-server[.exe]
+out/client/<host>/peardock-client[.exe]
+```
+
+Hosts: `linux-x64`, `linux-arm64`, `darwin-arm64`, `darwin-x64`, `win32-x64`, `win32-arm64`.
+
+### Why `scripts/bare-standalone.cjs` instead of plain `bare-build`?
+
+`bare-build` 1.x packs with Bare resolution but does **not** expose
+`bare-pack --imports`. Node packages such as `dockerode` need
+`bare-node-runtime/imports.json` so builtins (`events`, `stream`, …) map to
+`bare-*`. The peardock builder:
+
+1. `bare-pack` with bare-node-runtime imports + small shims/stubs
+2. Embeds the bundle into a portable Bare runtime ELF/Mach-O/PE (same as
+   `bare-build --standalone`)
+
+Shims under `build/`:
+
+| Path | Purpose |
+|------|---------|
+| `shims/http.cjs` | Unix `socketPath` for Docker (bare-http1 is TCP-only) |
+| `shims/url.cjs` | Legacy `url.resolve` / `parse` for docker-modem |
+| `stubs/ssh2.cjs` | docker-modem optional SSH (local socket only) |
+| `stubs/grpc-js.cjs` | dockerode BuildKit gRPC sessions (not used for Engine API) |
+
+### Run server binary
+
+```bash
+# Identity lives next to the binary by default (.env)
+./out/server/linux-x64/peardock-server
+
+# Or point at a home directory
+PEARDOCK_HOME=/var/lib/peardock ./peardock-server
+# / PEARDOCK_ENV=/etc/peardock.env
+```
+
+Requires: Docker Engine socket (`/var/run/docker.sock`) and network for HyperDHT.
+
+### Run client binary (agent)
+
+```bash
+./out/client/linux-x64/peardock-client
+./out/client/linux-x64/peardock-client --connect <server-public-key-hex>
+```
+
+Full **desktop GUI** still uses Pear + pear-electron:
+
+```bash
+npm run dev   # pear run -d .
+```
+
+(Electron-forge installers can follow the [hello-pear-electron](https://github.com/holepunchto/hello-pear-electron)
+pattern later.)
+
+---
+
+## Gitea CI — rolling release (`RELEASE_TOKEN`)
+
+Workflow: `.gitea/workflows/release-rolling.yml`
+
+### Secret
+
+In the Gitea repo **Settings → Secrets**:
+
+| Name | Value |
+|------|--------|
+| `RELEASE_TOKEN` | Personal access token with **repository** write (create/delete releases + upload assets) |
+
+Optional:
+
+| Name | Value |
+|------|--------|
+| `GITEA_URL` | Forge base URL if not the same as the Actions host (e.g. `https://git.example.com`) |
+
+### Behaviour
+
+1. On every push to `main` / `master` (and manual dispatch), matrix-builds
+   server + client for desktop hosts via `npm run make:<product>:<host>`.
+2. `publish` job downloads artifacts and runs
+   `scripts/gitea-rolling-release.sh`.
+3. That script **replaces** the release tagged `rolling` (delete + recreate) and
+   uploads:
+
+   - `peardock-server-<host>[.exe]`
+   - `peardock-client-<host>[.exe]`
+   - `SHA256SUMS`
+
+### Manual publish (from a machine with artifacts)
+
+```bash
+export RELEASE_TOKEN=...
+export GITEA_URL=https://your.gitea.host
+export GITEA_OWNER=snxraven
+export GITEA_REPO=peardock
+npm run make:all   # or copy CI artifacts into out/
+npm run release:rolling
+```
+
+---
+
+## Source tarball + checksums (legacy / Node install)

 ```bash
 chmod +x scripts/release-checksums.sh
@@ -9,60 +140,55 @@ chmod +x scripts/release-checksums.sh
 GPG_KEY_ID=YOUR_KEY_ID ./scripts/release-checksums.sh dist/
 ```

-Artifacts:
-
 | File | Purpose |
 |------|---------|
 | `peardock-<ver>-<stamp>.tar.gz` | Source/runtime tree (no node_modules) |
 | `*.sha256` | SHA-256 checksum |
 | `*.asc` | Detached GPG signature (if keyed) |

-Verify:
-
-```bash
-cd dist
-sha256sum -c peardock-*.sha256
-gpg --verify peardock-*.tar.gz.asc peardock-*.tar.gz   # if signed
-```
-
-## Server install from release
-
 ```bash
 tar -xzf peardock-*.tar.gz -C /opt/peardock
 cd /opt/peardock && npm ci --omit=dev
+# Prefer binary: copy peardock-server into place and set ExecStart
 cp deploy/peardock.service /etc/systemd/system/
 systemctl enable --now peardock
 ```

-## Pear desktop app
+Update `deploy/peardock.service` `ExecStart` to the standalone binary when using
+Bare builds:
+
+```ini
+ExecStart=/opt/peardock/peardock-server
+Environment=PEARDOCK_HOME=/opt/peardock
+```
+
+---
+
+## Pear desktop app (GUI OTA)

 ```bash
 npm ci
 pear stage .
 pear release .
-# Distribute pear:// link or channel per Pear docs
+# Distribute pear:// link per Pear docs
 ```

+---
+
 ## Certification soak (24h)

 ```bash
 # Terminal 1
-npm run server
+./out/server/linux-x64/peardock-server
+# or: npm run server

-# Terminal 2 — 24 hours
+# Terminal 2
 SOAK_DURATION_MS=86400000 npm run soak
-# or: node scripts/soak.js --hours 24
 ```

-Exit 0 = Docker remained reachable within failure threshold.
-
-## Load / fuzz in CI
-
-Included in `npm test`:
-
- `test/load.test.js` — concurrent HyperDHT pings  
- `test/fuzz.test.js` — schema/role fuzz  
+---

 ## Encoding profile

-Handshake returns `schemaVersion` and features. Default encoding remains JSON (`shared/encodings.js`); binary bulk uses `binaryStream*` + `push:binaryChunk`. Hyperschema can replace JSON value encodings without renaming methods.
+Handshake returns `schemaVersion` and features. Default encoding remains JSON
+(`shared/encodings.js`); binary bulk uses `binaryStream*` + `push:binaryChunk`.