Bare standalone packaging — scripts/bare-standalone.cjs, make.cjs, hosts.cjs, prepare-pack.mjs (kernel sync, node_modules flatten, optional sshcrypto.node omit)
Release rolling / release (push) Failing after 1m32s
Release rolling / release (push) Failing after 1m32s
Entries + OTA — bin/bare-os-*.mjs + lib/bare-os-ota.mjs (pear-runtime, --no-updates / BARE_OS_OTA_DISABLE) Upgrade links on seeder/booter package.json Gitea rolling — .gitea/workflows/release-rolling.yml + scripts/gitea-rolling-release.sh (RELEASE_TOKEN) by-arch + pear-ci — scripts/pear-stage-by-arch.sh, ci/snapshot-*.json (PEAR_PRIMARY_KEY) pear run retired from npm/PM2/docs; see docs/BINARY-RELEASE.md
This commit is contained in:
Raven Scott
@@ -2,7 +2,7 @@
|
||||
|
||||
**Prerequisites:** [Install and repository layout](02-install-and-repository-layout.md). **Time to read:** about seven minutes.
|
||||
|
||||
**Canonical refs:** [Compatibility matrix](../docs/reference/compatibility-matrix.md) · [Environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||||
**Canonical refs:** [Compatibility matrix](../docs/reference/compatibility-matrix.md) · [Environment appendix](../docs/reference/environment-and-posix-appendix.md) · [Binary releases](../docs/BINARY-RELEASE.md).
|
||||
|
||||
**One-page quick path:** [Get started](../docs/get-started.md) (prerequisites table, success criteria, failure matrix).
|
||||
|
||||
@@ -11,12 +11,12 @@
|
||||
## On this page
|
||||
|
||||
- [Why there are two processes](#why-there-are-two-processes)
|
||||
- [Run with Node (quick path)](#run-with-node-quick-path)
|
||||
- [Run with Pear (recommended for realistic behavior)](#run-with-pear-recommended-for-realistic-behavior)
|
||||
- [Pear channels and released keys](#pear-channels-and-released-keys)
|
||||
- [Run with Bare (dev checkout)](#run-with-bare-dev-checkout)
|
||||
- [Run released binaries](#run-released-binaries)
|
||||
- [Pear install and OTA channels](#pear-install-and-ota-channels)
|
||||
- [Common mistakes](#common-mistakes)
|
||||
- [Boot sequence in plain language](#boot-sequence-in-plain-language)
|
||||
- [Choosing Node versus Pear](#choosing-node-versus-pear)
|
||||
- [Choosing checkout versus binary](#choosing-checkout-versus-binary)
|
||||
|
||||
---
|
||||
|
||||
@@ -44,97 +44,93 @@ flowchart LR
|
||||
|
||||
---
|
||||
|
||||
## Run with Node (quick path)
|
||||
## Run with Bare (dev checkout)
|
||||
|
||||
<details>
|
||||
<summary><strong>When to expand this block</strong></summary>
|
||||
Use a git checkout + **`bare`** when developing. Host **`pear run`** is gone in Pear v3 — do not use it.
|
||||
|
||||
Use **Node** when you do not have Pear installed or you are bisecting protocol and seeding bugs with host stack traces identical to your toolchain. **Pear** is still the closest match to embedded / released apps (`npm run os:*`).
|
||||
|
||||
</details>
|
||||
|
||||
Run the seeder from its package directory so **`kernel/`** resolves correctly from the repo layout:
|
||||
|
||||
```bash
|
||||
cd packages/bare-os-seeder && node index.js
|
||||
```
|
||||
|
||||
In a **second** terminal, start the booter:
|
||||
|
||||
```bash
|
||||
cd packages/bare-os-booter && node index.js
|
||||
```
|
||||
|
||||
Default store paths are under **`~/.bare-os/corestore/**` for seeder and booter unless you set **`BARE_OS_SEED_STORE`**, **`BARE_OS_BOOT_STORE`**, or the shared base **`BARE_OS_HOST_DATA`**. See each package’s **`lib/paths.js`** for how overrides compose.
|
||||
|
||||
On a **fresh clone**, build **`kernel/bin/*`** and **`kernel/lib/bare/`** before staging: from the repo root run **`npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs`** (or **`npm run pretest`**, which also verifies kernel/seeder parity). Root **`npm run os:seeder`** runs those builds automatically before **`pear run --dev`**.
|
||||
|
||||
---
|
||||
|
||||
## Run with Pear (recommended for realistic behavior)
|
||||
|
||||
<details>
|
||||
<summary><strong>When to expand this block</strong></summary>
|
||||
|
||||
**Pear** exercises **`pear run --dev`**, hoisted **`node_modules`**, and **`BARE_OS_PEAR_*`** behavior. Install the [Pear CLI](https://docs.pears.com/) first; confirm with **`pear --version`**.
|
||||
|
||||
</details>
|
||||
|
||||
From the **repository root**:
|
||||
From the repo root (builds kernel tools for the seeder path):
|
||||
|
||||
```bash
|
||||
npm run os:seeder
|
||||
```
|
||||
|
||||
In another terminal:
|
||||
In a **second** terminal:
|
||||
|
||||
```bash
|
||||
npm run os:booter
|
||||
```
|
||||
|
||||
These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees **hoisted** workspace dependencies the same way **`npm ci`** does at the repo root. Without that step, **`pear run`** from inside a package directory can miss modules that live at the root **`node_modules`**.
|
||||
Or from package dirs: `cd packages/bare-os-seeder && bare index.js` (after ensuring `kernel/` is built).
|
||||
|
||||
> **Important**
|
||||
> **`os:seeder`** is an **npm script name**, not a Pear app name. Do not type `pear run os:seeder`.
|
||||
Default store paths are under **`~/.bare-os/corestore/**` for seeder and booter unless you set **`BARE_OS_SEED_STORE`**, **`BARE_OS_BOOT_STORE`**, or the shared base **`BARE_OS_HOST_DATA`**. See each package’s **`lib/paths.js`** for how overrides compose.
|
||||
|
||||
On a **fresh clone**, build **`kernel/bin/*`** and **`kernel/lib/bare/`** before staging: from the repo root run **`npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs`** (or **`npm run pretest`**, which also verifies kernel/seeder parity). Root **`npm run os:seeder`** runs those builds automatically.
|
||||
|
||||
---
|
||||
|
||||
## Pear channels and released keys
|
||||
## Run released binaries
|
||||
|
||||
When you change **`packages/bare-os-booter/lib/bare-module-manifest.json`** or run **`npm run sync:bare-manifest`**, **`bare-module-manifest.data.mjs`** is regenerated for Pear (sync script and **`npm run build -w bare-os-bare-libs`** **`prebuild`**). From the repo root, run **`npm run verify:manifest-data`** before **`pear stage`** so the JSON and **`.data.mjs`** stay aligned.
|
||||
Download **`bare-os-seeder-<ver>-<host>.tar.gz`** and **`bare-os-booter-<ver>-<host>.tar.gz`** from the Gitea **`rolling`** release (see [BINARY-RELEASE.md](../docs/BINARY-RELEASE.md)). The seeder archive includes **`kernel/`** next to the binary.
|
||||
|
||||
After **`pear stage`** and **`pear release`**, you receive **`pear://…`** links that point at released artifacts. Consumers normally run those keys rather than a raw git checkout, unless they use dev mode (**`pear run --dev .`**).
|
||||
```bash
|
||||
tar -xzf bare-os-seeder-0.1.0-linux-x64.tar.gz
|
||||
./bare-os-seeder --no-updates
|
||||
|
||||
Concrete channel names, keys, versioned links, and host-side environment variables (**`BARE_OS_PEAR_*`**, HTTP allow lists, TLS pin forwarding, **`ctx.bare`** toggles) are documented in **[PEAR-RUN.md](../docs/PEAR-RUN.md)**. Keep that file open when you embed the booter in a Pear app or wire OTA reload hooks.
|
||||
tar -xzf bare-os-booter-0.1.0-linux-x64.tar.gz
|
||||
./bare-os-booter --no-updates
|
||||
```
|
||||
|
||||
Local packed builds: **`npm run make:seeder:linux-x64`** (etc.) → **`out/bare-os-*-<host>/`**.
|
||||
|
||||
---
|
||||
|
||||
## Pear install and OTA channels
|
||||
|
||||
```bash
|
||||
pear install pear://1ycyj65xxgn6c5cirhtnm8aokkrpe9dzibriszyfkmfggc3opjzy # seeder
|
||||
pear install pear://khtauzttriz8dpgrphj79rfy98iwoatqm59fnogtsdqk5f1kg6ao # booter
|
||||
```
|
||||
|
||||
Packaged binaries embed **`pear-runtime`** against those upgrade links. Details: [BINARY-RELEASE.md](../docs/BINARY-RELEASE.md), [PEAR-RUN.md](../docs/PEAR-RUN.md).
|
||||
|
||||
---
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- Expecting **`pear run`** — removed in Pear v3; use binaries or **`pear install`**.
|
||||
- Running the seeder binary **without** **`kernel/`** beside it (or without **`BARE_OS_KERNEL_ROOT`**).
|
||||
- Starting only the booter with no live seeder / no prior drive tip.
|
||||
- **Booter times out** — No peer is serving the **`bare-os-v1`** topic, or the network cannot reach bootstrap nodes. Confirm the seeder is running and check **`HYPERSWARM_BOOTSTRAP`** if you use custom bootstraps ([Handbook — Chapter 7, troubleshooting](../handbook/07-operations-and-development.md#troubleshooting)).
|
||||
- **Missing `/bin` utilities under Pear** — Run **`npm run build -w bare-os-coreutils`** (and seed again) so the image contains a fresh **`/bin`** build.
|
||||
- **Wrong working directory for the seeder** — Start the seeder from **`packages/bare-os-seeder`** (or use the npm script from root) so kernel paths resolve.
|
||||
- **Expecting full POSIX job control** — The shell supports **`jobs`**, **`fg`**, **`bg`**, **`wait`**, background **`&`**, and logical stop/resume, but not monitor mode, real host process groups, or kernel **`SIGTSTP`** (see [Handbook ch.9 — Shell](../handbook/09-posix-utilities-shell-and-vfs.md)).
|
||||
- **Missing `/bin` utilities** — Run **`npm run build -w bare-os-coreutils`** (and seed again) so the image contains a fresh **`/bin`** build.
|
||||
|
||||
---
|
||||
|
||||
## Boot sequence in plain language
|
||||
|
||||
Once the booter has replicated enough of the **system** drive, it mounts the **personal** drive (creating one if needed), wires the merged VFS, and executes **`/boot/init.js`**. The stock kernel prints **`/etc/os-release`**, optional **`motd`**, runs **`/etc/bare-os/rc`** and sorted snippets under **`rc.d`**, then enters the interactive shell unless **`BARE_OS_SKIP_REPL`** or **`onboot`** lines consume the session. You do not need to memorize every phase to operate the system; when something fails **during** boot, enable **`BARE_OS_BOOT_TRACE`** (see [environment appendix](../docs/reference/environment-and-posix-appendix.md)) and read the phase lines on stderr.
|
||||
1. Seeder stages **`kernel/`** into a Hyperdrive and announces MBR on the swarm topic.
|
||||
2. Booter finds a peer, replicates the system drive, opens a personal drive, runs **`/boot/init.js`**.
|
||||
3. Optional: eligible booters later help cold joiners with block 0 / seed RPC.
|
||||
|
||||
Canonical **booter boot steps** (**`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`**) are summarized in [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md).
|
||||
Once the booter has replicated enough of the **system** drive, it mounts the **personal** drive (creating one if needed), wires the merged VFS, and executes **`/boot/init.js`**. When something fails **during** boot, enable **`BARE_OS_BOOT_TRACE`** (see [environment appendix](../docs/reference/environment-and-posix-appendix.md)).
|
||||
|
||||
Canonical **booter boot steps** are summarized in [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md).
|
||||
|
||||
---
|
||||
|
||||
## Choosing Node versus Pear
|
||||
## Choosing checkout versus binary
|
||||
|
||||
**Node** (`node index.js` in each package) is ideal when you are debugging protocol or seeding logic quickly and want stack traces identical to your host toolchain. **Pear** tracks production embedding more closely: module layout, **`pear run --dev`**, and host `**BARE_OS_PEAR_*`** toggles matter. If a bug appears **only** under Pear, compare with a Node run using the same Corestore paths to isolate runtime differences. [PEAR-RUN.md](../docs/PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.
|
||||
| Mode | When |
|
||||
|------|------|
|
||||
| **`npm run os:*` / `bare index.js`** | Day-to-day development in this repo |
|
||||
| **Rolling tarball / `out/` binary** | Operators, PM2, production-like hosts |
|
||||
| **`pear install`** | Install from upgrade channel with OTA |
|
||||
|
||||
---
|
||||
|
||||
## Related reading
|
||||
|
||||
- [Get started](../docs/get-started.md)
|
||||
- [Binary releases](../docs/BINARY-RELEASE.md)
|
||||
- [docs/troubleshooting.md](../docs/troubleshooting.md)
|
||||
- [Handbook — Protocol and disk](../handbook/03-protocol-and-disk.md)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user