Sam & Claude
b8d499e85c
7 renames (no plan/proposal/handoff/enhancement in filenames):
CLAWDIE-INSTALLER-HANDOFF.md → CLAWDIE-INSTALLER-VALIDATION.md
CLAWDIE-STUDIO-PROPOSAL.md → CLAWDIE-STUDIO.md
COLIBRI-SKILLS-PLAN.md → COLIBRI-SKILLS.md
FREEBSD-BUILD-LANE-HANDOFF.md→ FREEBSD-BUILD-LANE.md
GLASSPANE-TUI-ENHANCEMENTS.md→ GLASSPANE-TUI-DESIGN.md
MULTI-AGENT-HOST-PLAN.md → MULTI-AGENT-HOST.md
PLAN-WIKI-CLAWDIE-SI.md → WIKI-CLAWDIE-SI.md
16 cross-references updated across 10 files.
wiki-lint --strict: PASS (146 refs, 0 failures).
91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
---
|
|
title: Install
|
|
description: Provision the Clawdie host service with the clawdie binary.
|
|
---
|
|
|
|
**Command:** `clawdie apply --yes`
|
|
|
|
Colibri-based Clawdie is installed by the **`clawdie`** binary (crate
|
|
`crates/clawdie`). It discovers the host's ZFS layout and provisions the
|
|
`clawdie` service: storage datasets, a service user, and the rc.d (FreeBSD) or
|
|
systemd (Linux) unit that runs `colibri-daemon`.
|
|
|
|
This repo is a **Cargo workspace** — there is no `just`/npm install flow here.
|
|
Build the installer from the workspace:
|
|
|
|
```bash
|
|
cargo build -p clawdie --release
|
|
```
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
clawdie discover # read-only: OS, ZFS pools, datasets, spare disks
|
|
clawdie plan [--pool NAME] # show the deploy plan (dry-run, no writes)
|
|
clawdie apply [--pool NAME] # dry-run unless --yes is given
|
|
clawdie apply --yes # provision: storage layout + install the service
|
|
```
|
|
|
|
`apply` is a **dry-run by default** and prints the full step plan; it writes to
|
|
disk only with `--yes`. When the host has exactly one ZFS pool it is selected
|
|
automatically; with several, pass `--pool NAME`.
|
|
|
|
## Storage strategy
|
|
|
|
| Host | Behavior |
|
|
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
| FreeBSD | ZFS is **required**; datasets are created under the chosen pool. |
|
|
| Linux + ZFS + pool | Same — datasets under the pool. |
|
|
| Linux, no ZFS/pool | Falls back to plain directories, and reports the ZFS benefits plus any spare disks that could host a pool. |
|
|
|
|
ZFS layout under the pool:
|
|
|
|
```text
|
|
<pool>/clawdie (container, canmount=off)
|
|
<pool>/clawdie/db -> /var/db/clawdie
|
|
<pool>/clawdie/log -> /var/log/clawdie
|
|
```
|
|
|
|
## What `apply --yes` provisions
|
|
|
|
1. **Storage** — the datasets above (or plain `/var/db/clawdie` +
|
|
`/var/log/clawdie` on the plain-dirs fallback).
|
|
2. **Service user** — `clawdie` (nologin), owning the state directories
|
|
(`clawdie:clawdie`).
|
|
3. **Service** — the rc.d script (FreeBSD, via `daemon -u clawdie`) or systemd
|
|
unit (Linux, `User=clawdie`), installed and enabled to run
|
|
`/usr/local/bin/colibri-daemon`.
|
|
|
|
## Creating a pool (destructive)
|
|
|
|
On a host with a spare disk and no usable pool:
|
|
|
|
```bash
|
|
clawdie apply --pool NAME --create-pool /dev/DEV --yes
|
|
```
|
|
|
|
`--create-pool` runs `zpool create` on `DEV` and **destroys all data on it**, so
|
|
it is refused unless the disk is detected as empty (no partitions/filesystem/
|
|
mount, not the root disk). Override that guard with `--force` only if you are
|
|
certain.
|
|
|
|
## Safety
|
|
|
|
Disk-touching steps (`zfs`/`zpool create`, service install) run as root on the
|
|
target host. `discover`, `plan`, and a bare `apply` never write — preview with
|
|
`plan` first.
|
|
|
|
## Scope: what the installer does _not_ do (yet)
|
|
|
|
`clawdie` provisions the **host service** only. The wider service mesh — PF
|
|
egress, worker jails, PostgreSQL, Forgejo/Git, and the CMS/web service — was
|
|
provided by the legacy clawdie-ai `just` + Ansible orchestrator and is **not yet
|
|
part of the colibri installer**. Older pages that reference `just install`,
|
|
`just setup-db`, `just doctor`, and similar describe that legacy flow, not this
|
|
repo; they are being reconciled to the `clawdie` model.
|
|
|
|
## FreeBSD validation
|
|
|
|
The disk-touching and service-install paths are validated on real FreeBSD/Linux
|
|
hosts; discovery, plan, and disk-candidacy logic are unit-tested. See
|
|
`docs/CLAWDIE-INSTALLER-VALIDATION.md` for the FreeBSD validation runbook.
|