---
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 x86 → FileBrowser upload → registry register → GitHub mirror
~/.keysat/deploy-sites.sh landing docs     # push static sites; accepts: landing | docs | registry-landing
```

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). The
  manifest declares `['x86_64', 'aarch64']` but `publish.sh` only uploads x86_64 —
  **don't claim multi-arch as shipped** until publish handles both. (`riscv` target
  exists, unverified.)
- 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."