Keysat
843ff0e5d7
Glue files not covered by subproject repos: top-level docs, logo, keysat-design-system, and crosscheck tests. Subproject folders are gitignored (each has its own Gitea remote).
100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# 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](https://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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd licensing-service-startos
|
|
npm install
|
|
```
|
|
|
|
## Building
|
|
|
|
From `licensing-service-startos/`:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|