keysat-root/docs/guides/startos-packaging.md

paths

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 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). 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."