colibri/docs/guide/install/install.md

title	description
Install	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:

cargo build -p clawdie --release

Commands

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:

<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:

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 — is not yet part of the colibri installer. Pages that reference just install, just setup-db, just doctor, and similar describe a previous orchestrator; 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.