96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# 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)
|
||
- [Boot sequence in plain language](#boot-sequence-in-plain-language)
|
||
- [Choosing Node versus Pear](#choosing-node-versus-pear)
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## Choosing Node versus Pear
|
||
|
||
**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](../PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.
|
||
|
||
---
|
||
|
||
_Previous: [Chapter 2](02-install-and-repository-layout.md)_ · _Next: [Chapter 4 — Shell, PATH, and scripts](04-shell-path-and-scripts.md)_
|