Operator & Codex
d0e9349a46
Collapse the stale manual controlplane install page to a legacy landing point, update README install guidance to the orchestrator, and align public architecture docs with the service/platform namespace split and current Warden slot map. Sync the Astro docs consumers from docs/public. --- Build: pass Tests: pass — 2197 passed (164 files) --- Build: pass | Tests: pass — 2197 passed (650 files)
154 lines
4 KiB
Markdown
154 lines
4 KiB
Markdown
---
|
|
title: "Bastille on FreeBSD 15"
|
|
---
|
|
|
|
|
|
Clawdie uses Bastille as the host-side jail manager for its Warden runtime on
|
|
FreeBSD.
|
|
|
|
## Host Assumptions
|
|
|
|
- FreeBSD 15 host
|
|
- ZFS root pool
|
|
- Bastille installed from packages
|
|
- `warden0` bridge on `10.0.1.1/24` in the repo registry example
|
|
- host-side orchestration, not an operator jail
|
|
|
|
## Recommendation
|
|
|
|
Keep Bastille boring and explicit:
|
|
|
|
- bootstrap `15.0-RELEASE`
|
|
- keep the stock Bastille layout
|
|
- use `warden0` as the canonical bridge name
|
|
- use `10.0.1.0/24` as the default internal jail subnet example
|
|
- keep jails thin by default
|
|
- keep only the optional `db` jail thick
|
|
|
|
## Bootstrap
|
|
|
|
```sh
|
|
pkg install -y bastille
|
|
bastille bootstrap -p 15.0-RELEASE
|
|
```
|
|
|
|
## Canonical Service Jails
|
|
|
|
Default fixed service slots:
|
|
|
|
- `git` on `<subnet>.2`
|
|
- `cms` on `<subnet>.3`
|
|
- `llama-cpp` on `<subnet>.4` (llama-server, embeddings)
|
|
- `db` on `<subnet>.5`
|
|
|
|
The operator controlplane is not a jail in the current model. It runs on the
|
|
FreeBSD host and is published at `ai.<internal_base>`.
|
|
|
|
Example bring-up for the default install:
|
|
|
|
```sh
|
|
bastille create -B -g <subnet>.1 git 15.0-RELEASE <subnet>.2/24 warden0
|
|
bastille create -B -g <subnet>.1 cms 15.0-RELEASE <subnet>.3/24 warden0
|
|
bastille create -T -B -g <subnet>.1 db 15.0-RELEASE <subnet>.5/24 warden0
|
|
```
|
|
|
|
Apply internal hostnames after creation:
|
|
|
|
```sh
|
|
bastille config cms set host.hostname cms.home.arpa
|
|
bastille config git set host.hostname git.home.arpa
|
|
```
|
|
|
|
## Worker Bring-Up
|
|
|
|
Workers are service-owned execution environments and start in the high range:
|
|
|
|
- default worker: `10.0.1.101`
|
|
- future networked workers continue upward from there
|
|
|
|
Use the setup path rather than hand-writing worker create commands:
|
|
|
|
```sh
|
|
just setup -- --step jails --create
|
|
```
|
|
|
|
## Networking
|
|
|
|
The intended host-side network is:
|
|
|
|
- bridge: `warden0`
|
|
- gateway: `10.0.1.1`
|
|
- jailed subnet: `10.0.1.0/24`
|
|
|
|
If a VNET jail comes up without a `default` route, treat that as a provisioning
|
|
defect and fix the create command rather than applying ad hoc routes later.
|
|
|
|
## Thick vs thin
|
|
|
|
Clawdie keeps jails thin by default.
|
|
|
|
- thin jails share the Bastille release tree and save disk space
|
|
- the optional `db` jail stays thick because the database is long-lived state
|
|
and we want its base lifecycle to stay explicit
|
|
|
|
Thin jails do **not** automatically follow host patchlevels. They follow the
|
|
Bastille release tree they are mounted from. Updating the FreeBSD host alone
|
|
does not refresh that release tree.
|
|
|
|
In practice, coordinated updates need two steps:
|
|
|
|
1. update the host
|
|
2. update the Bastille release tree and then refresh or rebuild the affected
|
|
jails
|
|
|
|
Repo helper:
|
|
|
|
```sh
|
|
sudo just system-update
|
|
```
|
|
|
|
This runs the current-release patch path for the host, refreshes the Bastille
|
|
release tree, updates thin jails, and updates the optional `db` jail when
|
|
`DB_RUNTIME=jail`.
|
|
|
|
## Packages and Roles
|
|
|
|
Current setup steps own the jail bootstrap contract:
|
|
|
|
- `db` installs PostgreSQL + pgvector
|
|
- `git` installs plain git storage
|
|
- `cms` installs nginx and the Astro/Starlight web baseline; optional Strapi
|
|
content/bootstrap remains internal and deployment-specific
|
|
|
|
Do not bootstrap a separate operator jail. The FreeBSD host is the operator
|
|
surface.
|
|
|
|
## ZFS Layout
|
|
|
|
With the default Bastille + Clawdie settings, datasets should live under a
|
|
project prefix such as:
|
|
|
|
```text
|
|
zroot/clawdie-runtime/jails
|
|
zroot/clawdie-runtime/releases
|
|
zroot/clawdie-runtime/templates
|
|
```
|
|
|
|
## Snapshots
|
|
|
|
Snapshot persistent service jails before risky changes, for example:
|
|
|
|
```sh
|
|
zfs snapshot zroot/clawdie-runtime/jails/clawdie-db@pre-schema-14.mar.2026-1200
|
|
zfs snapshot zroot/clawdie-runtime/jails/clawdie-cms@pre-strapi-14.mar.2026-1230
|
|
```
|
|
|
|
Use user-facing snapshot names in `DD.mmm.YYYY-HHMM` format.
|
|
|
|
## Current Direction
|
|
|
|
- host orchestrator on FreeBSD
|
|
- Bastille-managed service and worker jails
|
|
- no dedicated operator jail in the active model
|
|
- shared internal surfaces named by role: `ai`, `cms`, `git`
|
|
- public web serving delegated to the `cms` jail instead of host nginx ownership
|