feat: documentation site

Docusaurus 3 docs-only site at docsite/, served statically by nginx under /docs on the marketing host. Covers getting started (self-hosted install through first server and first licence), the control plane, Vantage HQ, a reference section and operations. Wired into docker-compose.site.yml as docsite (3005:80) and into the image build workflow, rebuilding on its own directory only. Never added to the self-hosted compose file.
2026-07-28 15:46:33 +01:00
commit 11b1936bb2
44 changed files with 23669 additions and 0 deletions
@@ -0,0 +1,78 @@
+---
+id: accounts-and-signup
+title: Accounts and signup
+sidebar_label: Accounts and signup
+---
+
+Vantage HQ, at `vantage-hq.hostxtra.co.uk`, is where you manage the **account**
+behind your instances: your team, your instances, their licences and billing.
+
+## An account is a team, not a person
+
+One account holds many people and many instances. Everyone in it has an account
+role:
+
+| Role | Can |
+| --- | --- |
+| `owner` | Everything, including billing |
+| `admin` | Invite people, create instances, grant instance access |
+| `member` | Read what the account holds |
+
+Reading is open to any signed-in member. Every mutation except changing your own
+password requires `owner` or `admin`. Billing is owner-only.
+
+The three words are the same as the control plane's roles, on purpose — but they
+are separate things. Your account role governs the portal; your role *inside* an
+instance governs that instance.
+
+## Signing up
+
+Signup is **account-first**. Creating an account creates the account and you;
+it does not create a Vantage instance. Nothing exists in any control plane until
+you later create or link one.
+
+1. Go to the signup form.
+2. Enter your name, email and a password.
+3. Check your email and click the verification link.
+
+:::info Verify before you can sign in
+An unverified account gets a distinct "check your email" message rather than a
+generic authentication failure — the address is already known to be yours, so
+there is nothing to protect by being vague.
+:::
+
+Verification links are valid for **24 hours**. The token is 32 random bytes and
+only its SHA-256 hash is stored, so a leaked database yields no working links.
+
+If the verification email cannot be sent, the signup is rolled back rather than
+left stranded — retry rather than assuming a half-created account is in the way.
+
+## Signing in
+
+Email and password. The session is a cookie, separate from the control plane's:
+signing in to HQ does not sign you in to an instance, and vice versa.
+
+## What comes next
+
+| You want | Go to |
+| --- | --- |
+| A Vantage instance we run | [Cloud instances](./cloud-instances.md) |
+| To license an install you run | [Self-hosted instances](./self-hosted-instances.md) |
+| To add colleagues | [People and roles](./people-and-roles.md) |
+| To understand tiers and limits | [Licensing and entitlements](./licensing-and-entitlements.md) |
+
+## The portal layout
+
+Three destinations: **Overview**, **People**, **Billing**.
+
+Settings lives in the account menu rather than the nav, because it is your
+password rather than a place. The appearance toggle is there too.
+
+Overview lists your instances. Each is one record, closed to a row and open to
+its licence contents, members and actions. It opens by default when it is your
+only instance or when it needs attention, and your manual choice is remembered.
+
+There is deliberately no "your plan" card in the sidebar: tier, limits and
+expiry belong to a **licence**, and a licence belongs to one instance. An
+account with a Free cloud instance and a Professional self-hosted one has no
+single plan to show.