---
paths:
  - "licensing-service-startos/startos/**"
  - "licensing-service-startos/Makefile"
  - "licensing-service-startos/s9pk.mk"
  - "licensing-service-startos/Dockerfile"
  - "licensing-service-startos/package.json"
---

# StartOS packaging, build & release

Platform is **StartOS 0.4.0.x** — LXC under the hood, so commands/paths reflect
that, not Docker. Wrapper is TypeScript on `@start9labs/start-sdk ^1.3.2`, bundled
with `@vercel/ncc`, Node 22.

## Build / install (from `licensing-service-startos/`)

```
make x86            # build keysat_x86_64.s9pk   (npm check+build → start-cli s9pk pack)
make arm            # build keysat_aarch64.s9pk  (verified to build; ~1.5 min Rust cross-compile)
make universal      # single multi-arch package (both arches)
make install        # install newest *.s9pk to the host in ~/.startos/config.yaml
make clean          # wipe artifacts + node_modules (auto-reinstalls on next build)
npm run check       # tsc --noEmit on the wrapper
npm run prettier    # prettier --write startos  (NOT enforced; see testing.md)
```

Auth for `make install` is the developer key at `~/.startos/developer.key.pem`
(private — never commit/share).

## ALWAYS: bump the version before building

Edit `startos/versions/v0.2.0.ts` — increment `version: '0.2.0:N'` and prepend a
`ROUTINE_NOTES[0]` entry — **before** `make x86` or `publish.sh`. Start9 0.4.x
silently no-ops an install whose version equals what's already installed. Run
`cargo check` from `licensing-service/` first so the build doesn't fail downstream.

## Release (operator-local scripts, in `~/.keysat/`, gitignored)

```
~/.keysat/publish.sh                       # version-gate → make universal → FileBrowser upload → registry register → GitHub mirror → make install (deploy to live host, best-effort)
~/.keysat/deploy-sites.sh                   # DEFAULT: deploy ALL public sites (landing + docs). Re-uploads every site so the live HTML always matches its repo, even unmodified ones — preferred over a single-site deploy so nothing drifts.
~/.keysat/deploy-sites.sh docs              # or name one/more explicitly: landing | docs
```

Prefer the no-arg form (all sites) whenever pushing any site change, so every
public page is at its repo's latest. The site repos are independent of the s9pk
release, so deploying them is separate from `publish.sh`.

Credentials: `~/.keysat/filebrowser.env` (`chmod 600`); env `KEYSAT_FB_USER`,
`KEYSAT_FB_PASS`. Daemon runtime env: `KEYSAT_ADMIN_API_KEY`, `KEYSAT_LICENSE`,
`KEYSAT_OPERATOR_NAME`, `KEYSAT_PUBLIC_URL`, `BTCPAY_URL`, `BTCPAY_BROWSER_URL`,
`BTCPAY_PUBLIC_URL`.

## Arch & manifest

- Both `x86_64` and `aarch64` build cleanly (arm verified 2026-06-12). `publish.sh`
  now builds a single universal `keysat.s9pk` via `make universal` (both arches in
  one package — the registry holds one s9pk per version, so a per-arch split won't
  work), matching the manifest's `['x86_64', 'aarch64']` claim. **Pending a
  verification build**: the combined universal pack hasn't been run end-to-end yet;
  confirm the registry index lists both arches on the first publish. (`riscv` target
  exists, unverified; not in the manifest, so `make universal` excludes it.)
- Manifest `license` is `LicenseRef-Keysat-1.0`, matching the package-root
  `LICENSE` SPDX id.

## Known issue: registry icon

`start-cli registry info set-icon` stores the icon fine (round-trips at 96×96 and
256×256 PNG), but the StartOS marketplace header may still show the storefront
fallback. The operator may have to paste the data URL into the local "Configure
Registry" modal manually. Confirm visually before claiming "done."