Keysat
9e4c36c05b
Ports the in-repo KEYSAT_AGENT_GUIDE.md into the docs site as a first-class page rather than linking out to a raw markdown file on GitHub. The page covers authentication, scoped API keys, OpenAPI discovery, error envelope conventions, common workflows (issue / revoke / find / cancel / change-tier / free-machine), webhook event types + signature verification, robust-agent patterns, a "comp-license-via-email" recipe, and the operator-only operations that aren't exposed to any scoped key. Sidebar gains an "Agent integration" entry under Get started on every page (index, install, integrate, wire-format, operate, agent itself). Docs index "These docs cover" + "Where to next" grids each gain a third card pointing at the agent guide so it's discoverable from the introduction page even for visitors who don't scan the sidebar.
163 lines
9.2 KiB
HTML
163 lines
9.2 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Keysat Docs — Operate</title>
|
|
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg">
|
|
<link rel="stylesheet" href="docs.css">
|
|
</head>
|
|
<body>
|
|
|
|
<div class="topnav">
|
|
<a href="https://keysat.xyz" class="brand" title="Back to keysat.xyz"><img src="assets/keysat-mark.svg" alt=""><span>Keysat</span></a>
|
|
<span class="docs-tag">Docs</span>
|
|
</div>
|
|
|
|
<div class="layout">
|
|
<aside class="side">
|
|
<div class="group">
|
|
<div class="glabel">Get started</div>
|
|
<a href="index.html">Introduction</a>
|
|
<a href="install.html">Install & setup</a>
|
|
<a href="integrate.html">Integrate the SDK</a>
|
|
<a href="agent.html">Agent integration</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Concepts</div>
|
|
<a href="index.html#architecture">Architecture</a>
|
|
<a href="index.html#products-policies">Products & policies</a>
|
|
<a href="index.html#discounts">Discount codes</a>
|
|
<a href="index.html#revocation">Revocation strategy</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Reference</div>
|
|
<a href="wire-format.html">Wire format</a>
|
|
<a href="integrate.html#api">Admin API</a>
|
|
<a href="integrate.html#sdks">SDKs</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Operate</div>
|
|
<a href="operate.html#backups" class="active">Backups</a>
|
|
<a href="operate.html#migrate">Migrate hardware</a>
|
|
<a href="operate.html#troubleshooting">Troubleshooting</a>
|
|
</div>
|
|
</aside>
|
|
|
|
<main class="prose">
|
|
<div class="crumb">Operate · Day-to-day</div>
|
|
<h1>Operate.</h1>
|
|
<p class="lead">Backups, migration, recovery, and the things that go wrong. The "you didn’t expect to need this page until you needed it" page.</p>
|
|
|
|
<h2 id="backups">Backups</h2>
|
|
<p>StartOS handles backups for you. By default, every service in your StartOS install is included in the same backup snapshot — you set the destination once (encrypted external drive, S3-compatible cloud, etc.) and StartOS schedules nightly snapshots.</p>
|
|
|
|
<p>The Keysat backup payload is intentionally tiny. It contains:</p>
|
|
|
|
<ul>
|
|
<li>The signing keypair (<code>/data/issuer-key.pem</code>).</li>
|
|
<li>The SQLite database (<code>/data/keysat.db</code>).</li>
|
|
<li>Migration history.</li>
|
|
</ul>
|
|
|
|
<p>That’s it. No log files (those rotate locally), no caches.</p>
|
|
|
|
<div class="callout warn">
|
|
<i data-lucide="alert-triangle"></i>
|
|
<p><strong>Verify your backup destination at least once.</strong> Restoring on a fresh Start9 with a corrupted backup is exactly the wrong moment to discover that your destination wasn’t actually configured. StartOS → Settings → Backups → Test.</p>
|
|
</div>
|
|
|
|
<p>Your BTCPay store data and your Bitcoin wallet are separate backups, handled by the BTCPay and Bitcoin Core packages respectively. Keep them on the same backup destination so they restore in lockstep.</p>
|
|
|
|
<h2 id="migrate">Migrating to new hardware</h2>
|
|
<p>The full migration path:</p>
|
|
|
|
<ol>
|
|
<li>On the old Start9, ensure your most recent backup is complete and includes Keysat. Confirm the destination is writable and that snapshots have finished.</li>
|
|
<li>On the new Start9, complete first-time setup with a fresh password. Don’t install any services yet.</li>
|
|
<li>StartOS → Settings → Backups → Restore. Point at the same destination. Pick the most recent snapshot.</li>
|
|
<li>StartOS restores all services in dependency order. Keysat will restore alongside BTCPay and Bitcoin Core. Bitcoin will need to re-sync if you’re using Bitcoin Core (consider <a href="https://utxo.live">utxo.live</a> for assumeutxo to skip IBD).</li>
|
|
<li>Once Keysat is running on the new box, your purchase URLs change — the LAN/Tor hostnames are different. Update any links you’ve published.</li>
|
|
</ol>
|
|
|
|
<p>The signing keypair restores along with the database, so all previously-issued licenses verify identically against the same public key. You don’t need to re-distribute the public key to your customers.</p>
|
|
|
|
<h2 id="signing-key">Rotating the signing key</h2>
|
|
<p>You generally don’t want to rotate the signing key — doing so invalidates every license you’ve ever issued. v0.1 doesn’t support rotation; the key is generated once at first start and never changed.</p>
|
|
|
|
<p>If you absolutely need to rotate (e.g. you suspect the keypair has leaked off the box):</p>
|
|
|
|
<ol>
|
|
<li>Stop Keysat.</li>
|
|
<li>Move <code>/data/issuer-key.pem</code> aside.</li>
|
|
<li>Restart Keysat — it will generate a fresh keypair on first run.</li>
|
|
<li>Re-issue all active licenses to existing customers using the new key. The admin UI doesn’t support bulk re-issuance yet; this is a manual SQL exercise.</li>
|
|
<li>Push a software update that swaps the embedded public key.</li>
|
|
</ol>
|
|
|
|
<p>The cleaner path, for v0.2 onward, will be to support a rolling rotation where both keys verify for a transition period.</p>
|
|
|
|
<h2 id="troubleshooting">Troubleshooting</h2>
|
|
|
|
<h3 id="t-btcpay-url">"Invalid BTCPay URL" when clicking Connect BTCPay</h3>
|
|
<p>Keysat is selecting a BTCPay URL that isn’t reachable from your browser. This usually means the picked URL is a StartTunnel-local <code>10.59.x.x</code> address rather than your LAN/mDNS one.</p>
|
|
<p>Fix: open BTCPay’s service page in a separate tab, copy the URL it shows under "Network — mDNS" or "Network — LAN", and confirm Keysat is using a similar shape. If you’re on Tor only, BTCPay needs to expose its admin UI over Tor too.</p>
|
|
|
|
<h3 id="t-payment-method">"Payment method unavailable" on first invoice creation</h3>
|
|
<p>BTCPay rejects the invoice request because the store has no configured wallet. Open BTCPay, find your store, and configure either an on-chain wallet or a Lightning node before retrying.</p>
|
|
|
|
<h3 id="t-webhook">Webhook deliveries failing</h3>
|
|
<p>Check the audit log in the admin UI — failed deliveries land there with the response status. Common causes:</p>
|
|
<ul>
|
|
<li>Endpoint URL no longer reachable. Hit it manually with <code>curl</code> from your laptop to confirm.</li>
|
|
<li>Endpoint rejecting on signature mismatch. Verify your endpoint is HMAC-validating against the secret you registered with.</li>
|
|
<li>Endpoint timing out. Endpoints have a 10s deadline. Move slow work behind a queue on your end.</li>
|
|
</ul>
|
|
|
|
<h3 id="t-db-locked">"database is locked" errors in logs</h3>
|
|
<p>Almost always a sign that two daemon instances are racing on the same SQLite file — usually because of a misconfigured supervisor. Confirm only one Keysat container is running. If you’re seeing this on a fresh install with no customizations, file a bug report against the package version you’re running.</p>
|
|
|
|
<h3 id="t-time-skew">Licenses verifying as "expired" immediately after issue</h3>
|
|
<p>Clock skew. Either the issuing host or the verifying host has the wrong time. Run NTP. StartOS keeps your Start9 in sync automatically; the issue is usually on the verifier side (e.g. an air-gapped buyer machine).</p>
|
|
|
|
<h2 id="logs">Reading the logs</h2>
|
|
<p>Keysat logs to stdout, captured by StartOS. Tail them from the StartOS dashboard — Service page → Logs → Live tail.</p>
|
|
|
|
<p>Useful log lines to grep for:</p>
|
|
|
|
<table class="t">
|
|
<thead><tr><th>Pattern</th><th>What it means</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>license issued</code></td><td>Successful license issuance. Includes license id and product.</td></tr>
|
|
<tr><td><code>btcpay webhook received</code></td><td>BTCPay delivered an event. Followed by a "settled" or "expired" disposition line.</td></tr>
|
|
<tr><td><code>auth failed</code></td><td>Bad admin API key on a request to <code>/v1/admin/*</code>.</td></tr>
|
|
<tr><td><code>signature mismatch</code></td><td>BTCPay webhook arrived with the wrong HMAC. Either misconfigured or actively malicious.</td></tr>
|
|
<tr><td><code>migration applied</code></td><td>A schema migration ran on startup. Normal during package updates.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2 id="getting-help">Getting help</h2>
|
|
<p>If you’re stuck:</p>
|
|
|
|
<ul>
|
|
<li>File an issue at <a href="https://github.com/keysat-xyz/keysat/issues">github.com/keysat-xyz/keysat/issues</a>. Include the package version (visible in the StartOS service page) and any relevant log lines.</li>
|
|
<li>Email <a href="mailto:licensing@keysat.xyz">licensing@keysat.xyz</a> for security-sensitive issues you don’t want to disclose publicly.</li>
|
|
</ul>
|
|
</main>
|
|
|
|
<aside class="toc">
|
|
<div class="label">On this page</div>
|
|
<a href="#backups">Backups</a>
|
|
<a href="#migrate">Migrate hardware</a>
|
|
<a href="#signing-key">Rotate signing key</a>
|
|
<a href="#troubleshooting">Troubleshooting</a>
|
|
<a href="#logs">Reading the logs</a>
|
|
<a href="#getting-help">Getting help</a>
|
|
</aside>
|
|
</div>
|
|
|
|
<script src="https://unpkg.com/lucide@latest"></script>
|
|
<script>lucide.createIcons();</script>
|
|
</body>
|
|
</html>
|