Keysat
203 lines
12 KiB
HTML
203 lines
12 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: Install & setup</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" class="active">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>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Project</div>
|
|
<a href="pricing.html">Pricing</a>
|
|
<a href="license.html">License</a>
|
|
</div>
|
|
<div class="group">
|
|
<div class="glabel">Operate</div>
|
|
<a href="operate.html#backups">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">Get started · Install & setup</div>
|
|
<h1>Install & setup.</h1>
|
|
<p class="lead">From bare Start9 to your first issued license, in roughly the order you’ll do it. Allow about an afternoon.</p>
|
|
|
|
<h2 id="prereq">Prerequisites</h2>
|
|
<ul>
|
|
<li>A Start9 server running StartOS 0.4.x (Server Pro, Server One, or DIY install).</li>
|
|
<li>Administrative access to the StartOS dashboard.</li>
|
|
<li>About 2 GB of free disk for Keysat itself; BTCPay’s requirements are larger and depend on your Bitcoin node mode.</li>
|
|
</ul>
|
|
|
|
<h2 id="install">Step 1: Install Keysat</h2>
|
|
<p>Two ways. Either gets you to the same place.</p>
|
|
|
|
<h3>Option A: from the Keysat marketplace (recommended)</h3>
|
|
<ol>
|
|
<li>In your StartOS dashboard, go to <strong>Marketplace → Add</strong>.</li>
|
|
<li>Paste <code>https://registry.keysat.xyz</code> as the URL.</li>
|
|
<li>Find <em>Keysat</em> in the marketplace listing and click <strong>Install</strong>.</li>
|
|
</ol>
|
|
|
|
<h3>Option B: sideload</h3>
|
|
<ol>
|
|
<li>Download <code>keysat.s9pk</code> from the <a href="https://github.com/keysat-xyz/keysat/releases">GitHub releases page</a>.</li>
|
|
<li>In your StartOS dashboard, go to <strong>Sideload</strong> and drag the file in.</li>
|
|
<li>Click <strong>Install</strong>.</li>
|
|
</ol>
|
|
|
|
<p>BTCPay Server is declared as a required dependency. If you don’t have it installed yet, StartOS will prompt you to install it as part of the same flow.</p>
|
|
|
|
<h2 id="admin-key">Step 2: Get your admin API key</h2>
|
|
<p>On Keysat’s StartOS service page, go to <strong>Actions → Show credentials</strong>. This reveals the 64-hex-character admin API key that gates all <code>/v1/admin/*</code> endpoints, including the admin UI.</p>
|
|
|
|
<div class="callout warn">
|
|
<i data-lucide="alert-triangle"></i>
|
|
<p><strong>Treat this key like a password.</strong> Anyone with it can issue, revoke, or read every license you’ve ever sold. Don’t paste it into Slack. Don’t check it into Git.</p>
|
|
</div>
|
|
|
|
<h2 id="admin-ui">Step 3: Open the admin UI</h2>
|
|
<p>Click the <strong>Launch UI</strong> button on Keysat’s service page. (StartOS surfaces this for any service that defines a <code>type: 'ui'</code> interface.) Paste the admin key from the previous step into the sign-in form.</p>
|
|
|
|
<p>From here on, you work in the admin UI. The StartOS Actions tab is reserved for the few operations that must happen outside the web UI: showing credentials, setting the web UI password, and activating or checking the Keysat self-license.</p>
|
|
|
|
<h2 id="operator-name">Step 4: Set your operator name</h2>
|
|
<p>In the admin UI, go to <strong>Settings</strong>. Set your operator name there: a short label that identifies <em>you</em> as the seller, e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.</p>
|
|
<p>This change is live-reloaded; you don’t need to restart the service.</p>
|
|
|
|
<h2 id="connect-btcpay">Step 5: Connect BTCPay</h2>
|
|
<p>Make sure BTCPay Server is running and has at least one <strong>store</strong> with a configured <strong>payment method</strong> (on-chain wallet or Lightning node). Without a payment method, BTCPay will reject Keysat’s invoice creation.</p>
|
|
|
|
<p>In the admin web UI, go to <strong>Settings → Payment providers</strong> and click <strong>Connect BTCPay</strong> (agents can drive the same connect over the API with <code>POST /v1/admin/btcpay/connect</code>). You’ll be redirected to BTCPay’s authorize page, where you grant Keysat the permissions it needs:</p>
|
|
|
|
<ul>
|
|
<li><code>btcpay.store.canviewstoresettings</code></li>
|
|
<li><code>btcpay.store.canmodifystoresettings</code> (to register the settle webhook)</li>
|
|
<li><code>btcpay.store.canviewinvoices</code></li>
|
|
<li><code>btcpay.store.cancreateinvoice</code></li>
|
|
<li><code>btcpay.store.canmodifyinvoices</code></li>
|
|
</ul>
|
|
|
|
<p>Once you confirm, BTCPay redirects back to Keysat with an API key and store id. Keysat:</p>
|
|
<ol>
|
|
<li>Stores the API key and store id in its local SQLite (encrypted at rest by StartOS).</li>
|
|
<li>Registers an outbound webhook subscription on the store, pointed at Keysat’s <code>/btcpay</code> webhook endpoint.</li>
|
|
<li>Verifies the connection by fetching the store’s payment-method list.</li>
|
|
</ol>
|
|
|
|
<div class="callout">
|
|
<i data-lucide="info"></i>
|
|
<p><strong>Connect is idempotent.</strong> If you click it again later, Keysat detects the existing connection and returns success without re-authorizing. To force a re-authorize, disconnect first from <strong>Settings → Payment providers</strong> (or <code>POST /v1/admin/btcpay/disconnect</code>).</p>
|
|
</div>
|
|
|
|
<p>Automating setup? On a <strong>sandbox</strong> daemon you can connect a non-mainnet BTCPay over the API instead of clicking, using a scoped key carrying the <code>payment_providers:write</code> scope. See <a href="agent.html#connect-btcpay">Agent integration: Connect BTCPay programmatically</a>.</p>
|
|
|
|
<p>Back in <strong>Settings → Payment providers</strong> (or via <code>GET /v1/admin/btcpay/status</code>), verify the wiring. It should report:</p>
|
|
|
|
<pre class="code"><span class="c"># Expected output:</span>
|
|
status: <span class="s">connected</span>
|
|
store: <span class="s">YOUR_STORE_ID</span>
|
|
webhook: <span class="s">registered</span>
|
|
payment_methods: <span class="s">[BTC-OnChain, BTC-LightningNetwork]</span></pre>
|
|
|
|
<p>If <code>payment_methods</code> is empty, head back to BTCPay and configure at least one before continuing.</p>
|
|
|
|
<h2 id="first-product">Step 6: Define your first product</h2>
|
|
<p>In the admin UI, go to <strong>Products → Create a new product</strong> and fill in:</p>
|
|
|
|
<ul>
|
|
<li><strong>Slug</strong>: lowercase, hyphens, will appear in the public URL. e.g. <code>bitcoin-ticker-pro</code>.</li>
|
|
<li><strong>Display name</strong>: shown on the buyer’s purchase page and on receipts.</li>
|
|
<li><strong>Description</strong>: one or two sentences; rendered as plain text.</li>
|
|
<li><strong>Price</strong>: the currency picker accepts sats, USD, or EUR. For sats, enter an integer (e.g. <code>50000</code>). For USD/EUR, enter the amount in dollars/euros. Keysat converts to BTC at invoice creation and the buyer pays the locked-in BTC amount.</li>
|
|
</ul>
|
|
|
|
<p>The product is created with no policies attached. Next:</p>
|
|
|
|
<h2 id="first-policy">Step 7: Define one or more policies</h2>
|
|
<p>Go to <strong>Policies → Create a new policy</strong>. Pick the product, then fill in:</p>
|
|
|
|
<ul>
|
|
<li><strong>Slug</strong>: lowercase id (e.g. <code>basic</code>, <code>pro</code>, <code>annual</code>). Not "special" in any way; the buy page renders a tier picker when a product has two or more public policies, with the initial tier chosen by <code>?policy=<slug></code> in the URL, then by the policy you mark "most popular", then by cheapest.</li>
|
|
<li><strong>Duration</strong>. Common choices: perpetual, 30 days (trial), 1 year. Recurring subscriptions are a separate toggle on the same form. Flip "Recurring subscription" + set a renewal cadence and Keysat handles the cycle (invoice → settle → re-sign) automatically.</li>
|
|
<li><strong>Max devices</strong>. <code>1</code> for single-seat, <code>0</code> for unlimited.</li>
|
|
<li><strong>Entitlements</strong>: pick from the product's catalog (you set up the catalog when you created the product on the previous step). The picked entitlements are baked into the signed license and your app reads them at verify time. Optionally toggle the "hide on buy page" eye icon on any entitlement to drop it from the tier card without un-granting it. Useful for higher tiers that use "Everything in Basic, plus:" marketing copy.</li>
|
|
<li><strong>Marketing bullets</strong> (optional): operator-authored ✓ items rendered on the tier card alongside the entitlements. Pure marketing copy, not enforced.</li>
|
|
</ul>
|
|
|
|
<p>If you're selling a multi-tier product (e.g. Basic / Pro / Max), repeat this step for each tier. Drag the cards in the Policies grid to set the order shown to buyers.</p>
|
|
|
|
<h2 id="purchase-url">Step 8: Share your purchase URL</h2>
|
|
<p>Your public purchase URL is now live at:</p>
|
|
|
|
<pre class="code">https://<your-keysat-host>/buy/<product-slug></pre>
|
|
|
|
<p>Buyers hit it, see your product, click "Pay", and BTCPay’s checkout takes over. On payment confirmation, Keysat receives a webhook from BTCPay, signs a license, and emails it to the buyer (if they entered an email) and shows it on the receipt page.</p>
|
|
|
|
<p>Test it end-to-end by creating a free-license discount code and redeeming it: the same code path runs, just without the payment leg.</p>
|
|
|
|
<h2 id="next">What’s next</h2>
|
|
<div class="next-grid">
|
|
<a class="next-card" href="integrate.html">
|
|
<span class="eyebrow">Hook it up</span>
|
|
<h4>Integrate the SDK →</h4>
|
|
<p>Embed your public key in your app and verify licenses offline.</p>
|
|
</a>
|
|
<a class="next-card" href="operate.html">
|
|
<span class="eyebrow">Run it</span>
|
|
<h4>Operate →</h4>
|
|
<p>Backups, migration to new hardware, and troubleshooting.</p>
|
|
</a>
|
|
</div>
|
|
</main>
|
|
|
|
<aside class="toc">
|
|
<div class="label">On this page</div>
|
|
<a href="#prereq">Prerequisites</a>
|
|
<a href="#install">1. Install Keysat</a>
|
|
<a href="#admin-key">2. Get admin key</a>
|
|
<a href="#admin-ui">3. Open the admin UI</a>
|
|
<a href="#operator-name">4. Set operator name</a>
|
|
<a href="#connect-btcpay">5. Connect BTCPay</a>
|
|
<a href="#first-product">6. First product</a>
|
|
<a href="#first-policy">7. Default policy</a>
|
|
<a href="#purchase-url">8. Purchase URL</a>
|
|
</aside>
|
|
</div>
|
|
|
|
<script src="https://unpkg.com/lucide@latest"></script>
|
|
<script>lucide.createIcons();</script>
|
|
<script src="docs.js"></script>
|
|
</body>
|
|
</html>
|