# First-party package build server (`pkg.clawdie.si`)

Lean scripts that turn the manual Phase 2–3 runbook in
[`../../docs/POUDRIERE-BUILD-SERVER.md`](../../docs/POUDRIERE-BUILD-SERVER.md) into
repeatable, idempotent steps. They run on the **`mother-build`** host (FreeBSD) and
produce the **first-party, signed** package repo that paid tenants pull from instead
of public mirrors — the package half of the trusted supply chain
([layered-soul `HIVE-ONBOARDING.md §10`](https://code.smilepowered.org/clawdie/layered-soul)).

These scripts deliberately do not provision the host (ZFS pool, base system,
networking) — that is hardware-specific and stays in the runbook. They assume a
FreeBSD host with a ZFS pool already present.

## Flow

```
poudriere-setup.sh     →  poudriere-build.sh     →  serve + client config
(config, key, jail,       (build ports into the     (nginx over the repo dir;
 ports tree)              signed repo)              clawdie-repo.conf.in)
```

1. **Set up** (idempotent; re-run anytime):

   ```sh
   mdo -u root ./poudriere-setup.sh --zpool zroot
   ```

   Generates `/usr/local/etc/ssl/clawdie-pkg.{key,pub}`, writes
   `/usr/local/etc/poudriere.conf` (only if absent), and creates the build jail and
   ports tree. The **public** key is what clients trust.

2. **Build** (signs the repo automatically via `PKG_REPO_SIGNING_KEY`):

   ```sh
   mdo -u root ./poudriere-build.sh --jail clawdie-amd64 --ports clawdie sysutils/colibri
   ```

   The `sysutils/colibri` port is the **canonical copy in the colibri repo**
   (`packaging/freebsd/port/sysutils/colibri/`) — copy it into the poudriere ports
   tree before building. This repo keeps no duplicate; the colibri repo owns the
   port (its `Makefile`/`pkg-plist`/`CARGO_CRATES`/rc.d track Colibri's source, and
   a `check-cargo-crates.sh` CI gate keeps it in sync). Generate `distinfo` on the
   build host with `make makesum`.

3. **Serve + clients.** Point nginx at
   `/usr/local/poudriere/data/packages/clawdie-amd64-clawdie` for `https://pkg.clawdie.si/`
   (osa/mother-build already carry `nginx` + `acme`). Generate each client's repo config
   from the template and ship the public key:

   ```sh
   sed "s#__PKG_URL__#https://pkg.clawdie.si/#; s#__PUBKEY_PATH__#/usr/share/keys/pkg/clawdie.pub#" \
       clawdie-repo.conf.in > /usr/local/etc/pkg/repos/clawdie.conf
   install -m 0444 /usr/local/etc/ssl/clawdie-pkg.pub /usr/share/keys/pkg/clawdie.pub
   ```

## Conventions

- POSIX `sh`, `set -u`, fixed `PATH`, `usage()` + strict arg parsing, **verify-then-act**
  (inputs and environment are validated before anything is created). Matches
  `live/operator-session/hw-report`.
- Idempotent: existing config, key, jail, and ports tree are left untouched.
- Defaults are overridable by flag or `POUDRIERE_*` env var.
