# Maintaining this package

Notes for whoever builds and ships the package. Nothing here is repeated
from `README.md`, which describes the runtime surface, or from
`instructions.md`, which is written for end users.

## Source layout

Kamado's own source is not vendored. The Makefile rsyncs `api/`, `ui/`
and `ckpool/` from a sibling checkout into `./kamado-src/`, which is
gitignored, before packing. Override the location with
`KAMADO_SRC=/path/to/KamadoPool`.

```text
startos/
  manifest/        id, image, volumes, bitcoind dependency
  main.ts          subcontainer, config rendering, daemons, health checks
  interfaces.ts    dashboard and the three stratum interfaces
  fileModels/      store.json
  actions/         the user-facing actions
  dependencies.ts  bitcoind requirement and the ZMQ task
  backups.ts       both volumes
  versions/        version graph and release notes
  init/            store seeding and init ordering
  i18n/            dictionaries for every user-facing string
assets/scripts/    ckpool run wrapper, TLS certificate init
Dockerfile         ckpool, dashboard, API, runtime
```

## Prerequisites

Node and npm, Docker with buildx, `rsync`, and `start-cli`.

`start-cli` must be recent enough to pack `instructions.md`. Run
`start-cli s9pk list-ingredients`: if `./instructions.md` is absent from
the output, the build will silently ship without instructions and the
StartOS instructions page will be blank. Older builds also lack the
`--instructions` flag on `s9pk pack`.

`start-cli` resolves its configured StartOS host on every command,
including local ones like `s9pk pack`. The workspace config at
`.startos/config.yaml` (found by walking up from the working directory)
sets that host under `host.default`, and it must be a name that resolves
on the build machine even though packing never contacts it. The template
that `s9pk init-workspace` writes points at a Start9 development host,
which is what produces `Failed to resolve hostname` on a fresh workspace.

## Building

```sh
npm ci      # once
make setup  # once per boot: binfmt handlers and a multi-platform builder
make        # kamado-pool.s9pk, universal, ship this
```

`make x86` and `make arm` emit single-arch packages and skip the other
architecture, which is much faster while iterating.

Only the CKPool and runtime stages are built for the target
architecture, and the aarch64 half of those runs under emulation on an
x86 host, which is why `make setup` is needed. The dashboard and API
stages pin `--platform=$BUILDPLATFORM` and cross compile instead: the
dashboard emits architecture-independent assets, and the API is
`CGO_ENABLED=0` with a pure-Go SQLite driver, so `GOARCH` cross
compilation is exact and the two slowest stages never run emulated.

`make setup` installs binfmt handlers from `tonistiigi/binfmt`. The
older `multiarch/qemu-user-static` image ships a qemu whose emulated gcc
segfaults intermittently part way through the CKPool build, which
presents as an unexplained compiler failure in bundled jansson or in the
test link step.

## Build failures worth recognising

**`Failed to resolve hostname`.** The workspace host does not resolve.
See Prerequisites above.

**A compiler crash inside the CKPool stage.** Usually emulation, not the
code. Re-run `make`; cached layers make the retry cheap. If it recurs,
confirm `make setup` installed the current binfmt handlers.

**`429 Too Many Requests` pulling base images.** Docker Hub's anonymous
pull limit, reached easily when iterating. It clears on its own, or
`docker login` raises the ceiling immediately.

## Installing

```sh
make install
```

Requires the workspace host to point at a real server. Otherwise
sideload the produced `.s9pk` through the StartOS web interface, which
accepts a reinstall of the same version.

## Release checklist

1. Add a version file under `startos/versions/` with release notes in
   every locale the package already supports, and register it in
   `versions/index.ts` as `current`, moving the previous version into
   `other` so existing installs keep a migration path.
2. Keep `migrations` empty unless stored data actually changes shape,
   and say why in a comment either way.
3. Update `README.md` if the runtime surface changed: processes,
   volumes, interfaces, actions, tasks, health checks, backups or
   limitations. Update `instructions.md` if operator-facing behaviour
   changed.
4. Add any new user-facing string to the i18n dictionaries. The `i18n`
   helper is typed against them, so a missing entry fails the typecheck
   rather than shipping untranslated.
5. `npm run check` and `make`, then confirm the packed manifest reports
   the intended version and that `instructions.md` is present in the
   archive.