Update Docs
This commit is contained in:
Raven Scott
@@ -0,0 +1,169 @@
|
||||
# Get started with Bare OS
|
||||
|
||||
**Goal:** clone the repo, run a **seeder** and a **booter**, and reach an interactive shell. **Time:** about fifteen minutes if dependencies are already installed.
|
||||
|
||||
> [!CAUTION]
|
||||
> **Experimental research software** — not a production OS. Treat peers, keys, and vault data like any early-stage crypto and networking prototype.
|
||||
|
||||
> **Important**
|
||||
> Same message for forges that do not render GitHub-style alerts: keys, vault data, and network exposure need deliberate care.
|
||||
|
||||
---
|
||||
|
||||
## On this page
|
||||
|
||||
- [What you will have](#what-you-will-have-when-this-works)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Step 1 — Clone and install](#step-1--clone-and-install)
|
||||
- [Step 2 — Two terminals](#step-2--two-terminals-pear-recommended)
|
||||
- [Success criteria](#success-criteria)
|
||||
- [Node-only path](#node-only-path-no-pear)
|
||||
- [When something fails](#when-something-fails)
|
||||
- [Read next](#read-next)
|
||||
- [How the two processes connect](#how-the-two-processes-connect)
|
||||
|
||||
---
|
||||
|
||||
## What you will have when this works
|
||||
|
||||
- A **line shell** backed by **149** Tier-1 utilities under `/bin` (see [`packages/bare-os-coreutils/lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs)).
|
||||
- Two **Hyperdrives** mounted into one VFS: a **read-mostly system** image replicated from peers, and a **writable personal** drive for `$HOME`, `/.bare`, and similar paths. Short explainer: [Concepts — Two-drive model](concepts/two-drive-model.md).
|
||||
- A running **`/boot/init.js`** “kernel” and host-built **`ctx`** — not a hardware OS. See [User manual — Chapter 1](../users-manual/01-what-this-is.md).
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Notes |
|
||||
| --- | --- |
|
||||
| **Node.js ≥ 20** | Enforced in root [`package.json`](../package.json) `engines`. |
|
||||
| **Git** | To clone the repository. |
|
||||
| **Pear CLI** (recommended) | Required for **`npm run os:seeder`** and **`npm run os:booter`**. Install from the [Pear documentation](https://docs.pears.com/). Check with `pear --version`. |
|
||||
| **Network** | The booter must find a peer serving the **`bare-os-v1`** swarm topic within **`BARE_OS_BOOT_TIMEOUT_MS`** (default **60000** ms). |
|
||||
|
||||
<details>
|
||||
<summary><strong>Optional: Hyperswarm bootstrap nodes</strong></summary>
|
||||
|
||||
If discovery is flaky on your network, set **`HYPERSWARM_BOOTSTRAP`** to a comma-separated list of bootstrap nodes (see [Handbook — Chapter 7](../handbook/07-operations-and-development.md) and the [environment appendix](reference/environment-and-posix-appendix.md)).
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Clone and install
|
||||
|
||||
From a terminal:
|
||||
|
||||
```bash
|
||||
git clone https://git.ssh.surf/snxraven/bare-operating-system.git
|
||||
cd bare-operating-system
|
||||
npm ci
|
||||
```
|
||||
|
||||
The workspace must be installed from the **repository root** so Pear sees hoisted `node_modules` correctly (see [User manual — Chapter 2](../users-manual/02-install-and-repository-layout.md)).
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Two terminals (Pear recommended)
|
||||
|
||||
**Terminal A — seeder** (publishes the system Hyperdrive and MBR):
|
||||
|
||||
```bash
|
||||
npm run os:seeder
|
||||
```
|
||||
|
||||
**Terminal B — booter** (replicates the image, opens the personal drive, boots init):
|
||||
|
||||
```bash
|
||||
npm run os:booter
|
||||
```
|
||||
|
||||
These scripts run **`pear run --dev`** inside each package after [`scripts/ensure-pear-node-modules.mjs`](../scripts/ensure-pear-node-modules.mjs) links dependencies. **`os:seeder`** also builds coreutils and bare-libs before Pear starts.
|
||||
|
||||
> [!TIP]
|
||||
> **`os:seeder`** is an **npm script name**, not a Pear app name. Do not type `pear run os:seeder`.
|
||||
|
||||
> **Tip**
|
||||
> Released Pear keys and channels live in [PEAR-RUN.md](PEAR-RUN.md) if you prefer not to use a git checkout.
|
||||
|
||||
---
|
||||
|
||||
## Success criteria
|
||||
|
||||
- **Seeder:** logs show it is on the swarm and serving the staged image (wording varies by version; absence of fatal errors and steady “serving” / replication hints is what you want).
|
||||
- **Booter:** passes peer discovery, replication, and kernel start without exiting on timeout; you should get a **shell prompt** (or the stock boot path you configured).
|
||||
|
||||
If the booter exits with a **timeout**, the seeder is not visible on the topic, or the network cannot reach peers — see [When something fails](#when-something-fails).
|
||||
|
||||
---
|
||||
|
||||
## Node-only path (no Pear)
|
||||
|
||||
From the repo root, build staged artifacts once:
|
||||
|
||||
```bash
|
||||
npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
cd packages/bare-os-seeder && node index.js
|
||||
```
|
||||
|
||||
In a second terminal:
|
||||
|
||||
```bash
|
||||
cd packages/bare-os-booter && node index.js
|
||||
```
|
||||
|
||||
Full detail: [User manual — Chapter 3](../users-manual/03-running-seeder-and-booter.md).
|
||||
|
||||
---
|
||||
|
||||
## When something fails
|
||||
|
||||
| Symptom | First checks |
|
||||
| --- | --- |
|
||||
| **`pear: command not found`** | Install [Pear](https://docs.pears.com/) or use the [Node-only path](#node-only-path-no-pear). |
|
||||
| **Booter timeout** | Seeder running? Same machine or routable network? **`HYPERSWARM_BOOTSTRAP`** if isolated. |
|
||||
| **Missing `/bin` utilities** | Run **`npm run build -w bare-os-coreutils`** and restart the seeder so the image includes a fresh `/bin`. |
|
||||
| **Wrong cwd for seeder** | Prefer root **`npm run os:seeder`** or **`cd packages/bare-os-seeder`** so kernel paths resolve. |
|
||||
|
||||
Deeper help: [User manual — Chapter 7](../users-manual/07-troubleshooting-and-operations.md) · [Troubleshooting router](troubleshooting.md) · [FAQ](faq.md).
|
||||
|
||||
---
|
||||
|
||||
## Read next
|
||||
|
||||
| I want to… | Go to |
|
||||
| --- | --- |
|
||||
| See the full doc map | [Documentation home](README.md) · [Documentation sitemap](sitemap.md) |
|
||||
| Understand two drives and boot | [Concepts](concepts/README.md) |
|
||||
| Use the shell and identity | [User manual](../users-manual/README.md) |
|
||||
| Read the architecture story | [Handbook](../handbook/README.md) |
|
||||
| Extend `/bin` or `ctx` | [Developer guide](../developer-guide/README.md) |
|
||||
| Look up env vars and versions | [Environment appendix](reference/environment-and-posix-appendix.md) · [Compatibility matrix](reference/compatibility-matrix.md) |
|
||||
|
||||
---
|
||||
|
||||
## How the two processes connect
|
||||
|
||||
Logical flow (not every wire message). In text: the **seeder** publishes **MBR block 0** and Hyperdrive blocks on the **`bare-os-v1`** swarm topic; the **booter** discovers peers, reads the MBR, opens the **system** drive, then the **personal** drive, builds **`ctx`**, and runs **`/boot/init.js`**.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Seeder[bare-os-seeder]
|
||||
Topic[Swarm bare-os-v1]
|
||||
Booter[bare-os-booter]
|
||||
Init["/boot/init.js"]
|
||||
Seeder -->|publish MBR plus blocks| Topic
|
||||
Booter -->|discover replicate| Topic
|
||||
Booter --> Init
|
||||
```
|
||||
|
||||
Normative byte layout and RPC IDs: [Handbook — Chapter 3](../handbook/03-protocol-and-disk.md) · [Protocol reference](reference/package-bare-os-protocol.md).
|
||||
|
||||
---
|
||||
|
||||
_Links from this file are checked by **`scripts/verify-doc-links.mjs`** (relative `.md` targets only)._
|
||||
Reference in New Issue
Block a user