docs updates

2026-04-04 08:31:39 -04:00
parent 0e53351349
commit 081e4c587c
64 changed files with 2052 additions and 1273 deletions
@@ -0,0 +1,81 @@
+# Chapter 3 — Running seeder and booter
+
+**Prerequisites:** [Install and repository layout](02-install-and-repository-layout.md). **Time to read:** about seven minutes.
+
+---
+
+## 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)
+- [Common mistakes](#common-mistakes)
+
+---
+
+## Why there are two processes
+
+The **seeder** owns the **publisher** side: it stages the kernel tree into a system Hyperdrive, writes the **MBR** block that points at drive keys, and stays on the swarm so others can replicate.
+
+The **booter** owns the **consumer** side: it looks up peers on the same topic, replicates the system drive, attaches or creates a **personal** drive, and starts the in-image runtime (**`/boot/init.js`**, shell, initd, cron as configured).
+
+You almost always run them as **two separate processes** (two terminal tabs or windows). The booter needs a live seeder (or an already-replicated drive) to make progress within its boot timeout.
+
+---
+
+## Run with Node (quick path)
+
+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.
+
+---
+
+## Run with Pear (recommended for realistic behavior)
+
+From the **repository root**:
+
+```bash
+npm run os:seeder
+```
+
+In another 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`**.
+
+**Do not** type `pear run os:seeder` — **`os:seeder`** is an **npm script name**, not a Pear application name.
+
+---
+
+## Pear channels and released keys
+
+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 .`**).
+
+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](../PEAR-RUN.md)**. Keep that file open when you embed the booter in a Pear app or wire OTA reload hooks.
+
+---
+
+## Common mistakes
+
+- **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.
+
+---
+
+_Previous: [Chapter 2](02-install-and-repository-layout.md)_ · _Next: [Chapter 4 — Shell, PATH, and scripts](04-shell-path-and-scripts.md)_