Raven Scott
+52
-75
@@ -1,19 +1,30 @@
|
||||
# peardock release process
|
||||
|
||||
## Artifacts
|
||||
## Host matrix (64-bit only)
|
||||
|
||||
| Artifact | Builder | Platforms |
|
||||
|----------|---------|-----------|
|
||||
| **peardock-server** | Bare `bare-build --standalone` via `scripts/bare-standalone.cjs` | `linux-x64`, `linux-arm64`, `darwin-arm64`, `darwin-x64`, `win32-x64` (cross-compile OK) |
|
||||
| **peardock-client** | Electron Forge (`electron-forge package`) | Same hosts; **native rebuild** prefers a matching OS runner |
|
||||
No 32-bit (`ia32` / `armv7`) builds.
|
||||
|
||||
Server packing uses `package.json` `imports` (full **bare-node-runtime** map) so Node builtins resolve to `bare-*` modules inside the Bare standalone binary. Optional natives (`ssh2`, `@grpc/*`) map to stubs under `build/stubs/`.
|
||||
| Host | Server (Bare) | Client (Electron) |
|
||||
|------|---------------|-------------------|
|
||||
| `linux-x64` | ✅ cross from any OS | ✅ cross via electron-forge |
|
||||
| `linux-arm64` | ✅ | ✅ |
|
||||
| `darwin-x64` | ✅ | ✅ (unsigned from Linux CI) |
|
||||
| `darwin-arm64` | ✅ | ✅ (unsigned from Linux CI) |
|
||||
| `win32-x64` | ✅ | ✅ |
|
||||
| `win32-arm64` | ✅ | ✅ |
|
||||
|
||||
Client packing:
|
||||
Canonical list: `scripts/hosts.cjs` → `ALL_64`.
|
||||
|
||||
1. `npm run build:client-bundle` → `electron/app.bundle.cjs` (esbuild CJS of the GUI)
|
||||
2. `electron-forge package` with `forge.config.cjs` (`asar: false`, aggressive ignore list)
|
||||
3. Main process: `electron/main.cjs` (static server + Holesail control + Pear polyfill)
|
||||
---
|
||||
|
||||
## Builders
|
||||
|
||||
| Artifact | Tooling |
|
||||
|----------|---------|
|
||||
| **peardock-server** | `scripts/bare-standalone.cjs` — `bare-pack` with **bare-node-runtime** `imports` + stubs, then embed **bare-runtime** prebuild (`bare-build` platform hooks) |
|
||||
| **peardock-client** | `esbuild` → `electron/app.bundle.cjs`, then `electron-forge package --platform … --arch …` |
|
||||
|
||||
Server packing uses `package.json` `imports` so Node builtins resolve to `bare-*` under Bare. Optional natives (`ssh2`, `@grpc/*`) map to `build/stubs/*`.
|
||||
|
||||
---
|
||||
|
||||
@@ -22,111 +33,77 @@ Client packing:
|
||||
```bash
|
||||
npm ci
|
||||
|
||||
# Server — this host only
|
||||
npm run make:bin
|
||||
# or explicit:
|
||||
npm run make:server:linux-x64
|
||||
npm run make:server:darwin-arm64
|
||||
# All 64-bit server + client hosts (same as CI)
|
||||
npm run make # or: node scripts/make.cjs all
|
||||
|
||||
# Server — all hosts
|
||||
# Server only / client only
|
||||
npm run make:server
|
||||
npm run make:client
|
||||
|
||||
# Client — this host
|
||||
npm run start:client # dev
|
||||
# Single host
|
||||
npm run make:server:linux-x64
|
||||
npm run make:server:win32-arm64
|
||||
npm run make:client:darwin-arm64
|
||||
# Windows / Linux equivalents: make:client:win32-x64, make:client:linux-x64, …
|
||||
|
||||
# Both (server all hosts + client this host)
|
||||
npm run make
|
||||
npm run make:client:win32-arm64
|
||||
```
|
||||
|
||||
Outputs:
|
||||
|
||||
```
|
||||
out/peardock-server-<host>/peardock-server[.exe]
|
||||
out/peardock-<platform>-<arch>/ # Electron app tree (e.g. peardock.app on macOS)
|
||||
out/peardock-<platform>-<arch>/ # e.g. peardock.app on macOS
|
||||
```
|
||||
|
||||
### Server install smoke
|
||||
Override host lists:
|
||||
|
||||
```bash
|
||||
./out/peardock-server-linux-x64/peardock-server
|
||||
# prints public key; needs Docker socket
|
||||
```
|
||||
|
||||
### Client smoke
|
||||
|
||||
```bash
|
||||
open out/peardock-darwin-arm64/peardock.app # macOS
|
||||
# or ./out/peardock-linux-x64/peardock-client
|
||||
PEARDOCK_SERVER_HOSTS=linux-x64,win32-x64 \
|
||||
PEARDOCK_CLIENT_HOSTS=darwin-arm64,linux-x64 \
|
||||
npm run make
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gitea CI rolling release
|
||||
|
||||
Workflow: [`.gitea/workflows/release-rolling.yml`](../.gitea/workflows/release-rolling.yml)
|
||||
|
||||
Workflow: [`.gitea/workflows/release-rolling.yml`](../.gitea/workflows/release-rolling.yml)
|
||||
Script: [`scripts/gitea-rolling-release.sh`](../scripts/gitea-rolling-release.sh)
|
||||
|
||||
| Secret | Purpose |
|
||||
|--------|---------|
|
||||
| **`RELEASE_TOKEN`** | Gitea PAT with **repository release** read/write (required) |
|
||||
| `GITEA_URL` | Optional forge base URL if not inferred from `origin` / Actions context |
|
||||
| **`RELEASE_TOKEN`** | Gitea PAT with release write |
|
||||
| `GITEA_URL` | Optional forge base URL |
|
||||
|
||||
On push to `main` (and `workflow_dispatch`):
|
||||
On every push to `main` (and `workflow_dispatch`), the **ubuntu-latest** job:
|
||||
|
||||
1. `npm ci` + `npm test`
|
||||
2. Build **all server hosts** with bare-build (cross from Ubuntu)
|
||||
3. Build **linux-x64 client** with electron-forge on the Ubuntu runner
|
||||
4. Stage `dist/release/*.tar.gz` + `*.sha256`
|
||||
5. Recreate tag/release **`rolling`** and upload assets via Gitea API
|
||||
1. `npm ci`
|
||||
2. Cross-builds **all six** server hosts
|
||||
3. Cross-packages **all six** Electron clients (downloads per-target Electron + prebuilds)
|
||||
4. Stages `dist/release/peardock-{server,client}-${version}-${host}.tar.gz` + `.sha256`
|
||||
5. Recreates tag/release **`rolling`** and uploads assets
|
||||
|
||||
Dry-run locally (no upload):
|
||||
Dry-run locally:
|
||||
|
||||
```bash
|
||||
DRY_RUN=1 bash scripts/gitea-rolling-release.sh
|
||||
# or with upload:
|
||||
RELEASE_TOKEN=… GITEA_URL=https://your.gitea GITEA_OWNER=… GITEA_REPO=peardock \
|
||||
bash scripts/gitea-rolling-release.sh
|
||||
```
|
||||
|
||||
### Multi-OS client binaries
|
||||
### Notes
|
||||
|
||||
Ubuntu CI produces **linux-x64** client only (Electron native modules). For darwin/win32 clients:
|
||||
|
||||
- Run `npm run make:client:darwin-arm64` (etc.) on matching machines and attach archives to the release, or
|
||||
- Enable optional self-hosted matrix jobs in `release-rolling.yml` (commented template included).
|
||||
|
||||
Server binaries for all five hosts are produced from Linux via bare-runtime prebuilds.
|
||||
- **macOS clients from Linux** are **unsigned**. Users may need right-click → Open the first time.
|
||||
- **Native modules** must ship prebuilds for each target (Holepunch stack does). Rebuild-from-source is disabled for cross packages (`npm_config_build_from_source=false`).
|
||||
- **Server** cross-compile uses bare-runtime platform prebuilds (no Docker-in-Docker required to *build*; runtime still needs a Docker socket).
|
||||
|
||||
---
|
||||
|
||||
## Source tarball + checksums (legacy)
|
||||
## Source tarball + checksums
|
||||
|
||||
```bash
|
||||
./scripts/release-checksums.sh dist/
|
||||
GPG_KEY_ID=YOUR_KEY_ID ./scripts/release-checksums.sh dist/
|
||||
```
|
||||
|
||||
---
|
||||
## bare-node-runtime
|
||||
|
||||
## bare-node-runtime notes
|
||||
|
||||
- `package.json` `imports` mirror [bare-node-runtime/imports](https://github.com/holepunchto/bare-node-runtime) so `fs` / `http` / `net` / … resolve to `bare-fs` / `bare-http1` / `bare-net` under Bare.
|
||||
- `package.json` `imports` follow [bare-node-runtime](https://github.com/holepunchto/bare-node-runtime).
|
||||
- Entry `bin/peardock-server.mjs` loads `bare-node-runtime/global` only when `globalThis.Bare` is set.
|
||||
- Stack references: `hello-pear-bare-worker` (`bare-build --standalone --host …`), `bare-build`, `bare-runtime`, `bare-node-runtime`.
|
||||
|
||||
---
|
||||
|
||||
## Certification soak (24h)
|
||||
|
||||
```bash
|
||||
npm run server
|
||||
# other terminal:
|
||||
npm run soak:24h
|
||||
```
|
||||
|
||||
## Encoding profile
|
||||
|
||||
Handshake returns `schemaVersion` and features. Default encoding remains JSON (`shared/encodings.js`); binary bulk uses `binaryStream*` + `push:binaryChunk`.
|
||||
- References: `hello-pear-bare-worker`, `bare-build`, `bare-runtime`, `bare-pack --imports`.
|
||||
|
||||
Reference in New Issue
Block a user