keysat-root/BUILDING.md

Building and sideloading Keysat

This repo ships three components that you'll bundle into a single installable .s9pk:

• licensing-service/ — the Rust daemon (keysat binary).
• licensing-service-startos/ — the StartOS 0.4.0.x wrapper (TypeScript manifest + actions + Dockerfile).
• licensing-client-rust/ and licensing-client-ts/ — SDKs for downstream software. Not bundled into the .s9pk; published separately when you cut a release.

The Rust service's on-disk folder name is still licensing-service/ for continuity, but the crate, binary, and operator-visible branding are all Keysat now.

Prerequisites

1. A working StartOS 0.4.0.x development environment on a Linux or macOS workstation. Follow docs.start9.com if you haven't set this up yet.
2. start-cli installed on your PATH, with ~/.startos/developer.key.pem initialised (start-cli init).
3. Node 20+ (for the StartOS SDK, TypeScript).
4. Docker + buildx (for multi-arch image builds).
5. Network reachability from your workstation to your Start9 server (LAN or Tor — whatever you usually use to start-cli install).
6. A running BTCPay Server on the same Start9 server (Keysat depends on it).

You do not need Rust locally — the Dockerfile pulls a pinned rust:1.75-slim-bookworm image.

One-time setup

1. Fetch the shared build logic

Every 0.4.0.x wrapper includes s9pk.mk, which is maintained by the Start9 team. Fetch the current copy once:

cd licensing-service-startos
curl -o s9pk.mk https://raw.githubusercontent.com/Start9Labs/hello-world-startos/master/s9pk.mk

The Makefile include s9pk.mk line will error out until that file is in place.

2. Install TypeScript deps

cd licensing-service-startos
npm install

Building

From licensing-service-startos/:

# Build for all supported architectures (x86_64 + aarch64)
make

# Or just the architecture your Start9 box runs
make arm        # Raspberry Pi / Apple Silicon
make x86        # x86_64 StartOS server

The resulting artifact lands in licensing-service-startos/*.s9pk — a single file you can sideload.

Sideloading

cd licensing-service-startos
make install

This uses your ~/.startos/developer.key.pem to push the package to the Start9 server it's registered against. First-run prompts for the Start9 dashboard password; subsequent installs reuse the cached session.

If you prefer to upload the .s9pk through the StartOS dashboard UI, copy the file off your workstation and drag it into Sideload package from the dashboard.

First-boot checklist

Once installed, open Keysat in your StartOS dashboard and run these actions in order:

1. Set operator name — your display name, shown on the public homepage.
2. Connect BTCPay — opens a BTCPay consent page in your browser. Click Authorize; Keysat auto-detects your store and registers its inbound webhook.
3. Check BTCPay connection — confirms the authorize completed and the webhook is live.
4. Create product — one per thing you plan to sell.
5. Create policy — at least one per product, slugged default. Sets the shape of keys issued through the public purchase flow.

At this point your buyers can POST /v1/purchase against your Keysat URL, pay via BTCPay, and poll back for their license key.

Testing it end-to-end

Keysat ships with a cross-check test suite that independently signs license keys with a Python reference implementation and replays them through the Rust and TypeScript SDK parsers. See tests/crosscheck/README.md.

The simplest smoke test against a live install:

# On your workstation, once the service is running on StartOS:
curl https://<your-keysat-url>/v1/pubkey
curl https://<your-keysat-url>/healthz

The first returns the Ed25519 public key you'll bake into downstream software. The second should just return {"ok":true}.

Troubleshooting

• "KEYSAT_ADMIN_API_KEY must be at least 32 characters" — shouldn't happen from StartOS (the wrapper generates the key), but if you're running locally, openssl rand -hex 32 gives a valid value.
• "BTCPay not yet configured — purchases will return 503" — run Connect BTCPay from the StartOS dashboard.
• Rebuilds don't reflect Rust source changes — Docker layer caching is aggressive; make clean before make to force a full rebuild.
• Existing installs using LICENSING_* env vars — the daemon still reads those as a fallback for one release cycle. New installs set KEYSAT_* directly.