docs: Self review of doc pages
This commit is contained in:
@@ -20,9 +20,9 @@ role:
|
||||
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.
|
||||
These are the same three words your instances use, but they are separate things.
|
||||
Your account role controls what you can do in the portal. Your role inside an
|
||||
instance controls what you can do there.
|
||||
|
||||
## Signing up
|
||||
|
||||
@@ -38,14 +38,19 @@ Verification links are valid for **24 hours**.
|
||||
|
||||
## Signing in
|
||||
|
||||
Use the Email and password used in the signup form to login to the HQ, signing in to HQ does not sign you in to an instance, and vice versa.
|
||||
Sign in at [Vantage HQ](https://vantage-hq.hostxtra.co.uk) with the email and
|
||||
password from the signup form.
|
||||
|
||||
HQ and your Vantage instances have separate sessions: signing in to HQ does not
|
||||
sign you in to an instance, and signing in to an instance does not sign you in
|
||||
to HQ.
|
||||
|
||||
## 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 licence 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) |
|
||||
|
||||
@@ -55,4 +60,4 @@ Three destinations: **Overview**, **People**, **Billing**.
|
||||
|
||||
- Overview lists your instances.
|
||||
- People shows all the account members and their roles.
|
||||
- Billing show the current subscriptions and subscription management.
|
||||
- Billing shows your current subscriptions and lets you manage them.
|
||||
|
||||
+16
-12
@@ -12,25 +12,29 @@ customer reference and nothing sensitive.
|
||||
The Billing page requires the **owner-only** account role.
|
||||
:::
|
||||
|
||||
## Buying A Plan
|
||||
## Buying a plan
|
||||
|
||||
Buying a plan license can be found in Vantage HQ by clicking on the **Buy a Plan** button on the **Overview** page.
|
||||
In Vantage HQ, click **Buy a plan** on the **Overview** page.
|
||||
|
||||
### Cloud
|
||||
|
||||
On the **Buy A Plan** page you will need to select the **Deployment** to **Cloud** then chose your **Billing** cycle (Monthly or Annually).
|
||||
1. Set **Deployment** to **Cloud**.
|
||||
2. Choose a **Billing** cycle, monthly or annual.
|
||||
3. Choose a **Plan** and configure its features and server allowance.
|
||||
4. Enter an **Instance name** and click **Continue to payment**.
|
||||
|
||||
Then select your desired **Plan** and configure the features.
|
||||
|
||||
Finally specify the **Instance Name** and click the **Continue to payment** button.
|
||||
The instance is created and licensed as soon as payment confirms.
|
||||
|
||||
### Self-hosted
|
||||
|
||||
On the **Buy A Plan** page you will need to select the **Deployment** to **Self-Hosted** then chose your **Billing** cycle (Monthly or Annually).
|
||||
1. Set **Deployment** to **Self-hosted**.
|
||||
2. Choose a **Billing** cycle, monthly or annual.
|
||||
3. Choose a **Plan** and configure its features and server allowance.
|
||||
4. Enter an **Instance name** and click **Continue to payment**.
|
||||
|
||||
Then select your desired **Plan** and configure the features.
|
||||
|
||||
Finally specify the **Instance Name** and click the **Continue to payment** button.
|
||||
Payment creates a placeholder instance with no licence yet. You then paste your
|
||||
install's instance ID to have the licence issued. See
|
||||
[Self-hosted instances](./self-hosted-instances.md).
|
||||
|
||||
## Cancelling and failed payments
|
||||
|
||||
@@ -38,7 +42,7 @@ Cancelling, or a payment going past due, takes **no immediate licence action**.
|
||||
Your licence runs to its grace-padded expiry and then lapses normally. There is
|
||||
no mid-term cut-off.
|
||||
|
||||
For a cloud Free instance, lapsing eventually leads to deletion see
|
||||
For a cloud Free instance, lapsing eventually leads to deletion. See
|
||||
[Free tier](./free-tier.md). Paid instances are not deleted.
|
||||
|
||||
## Renewals
|
||||
@@ -47,4 +51,4 @@ At renewal the subscription bills again and the licence is reissued for the new
|
||||
term. It is also the only moment a scheduled **reduction** takes effect.
|
||||
|
||||
- Self-hosted customers: download and paste the reissued licence.
|
||||
- Cloud customers: the license is automatically linked to the instance.
|
||||
- Cloud customers: nothing to do. The licence is written to the instance for you.
|
||||
|
||||
+16
-16
@@ -9,18 +9,19 @@ A cloud instance is a Vantage control plane we run for you, reachable at
|
||||
|
||||
## Creating one
|
||||
|
||||
1. **Overview → New instance**.
|
||||
2. Choose a name and a slug.
|
||||
3. Create.
|
||||
1. On **Overview**, choose **Create a cloud instance**. Once you already have an
|
||||
instance, the same page offers **Buy a plan** instead.
|
||||
2. Choose **Cloud**, then the plan you want.
|
||||
3. Give the instance a name and confirm.
|
||||
|
||||
The instance is provisioned with you as its owner, and a Free licence is issued
|
||||
immediately. The owner user inside it gets your HQ password hash **copied**, not
|
||||
shared see [People and roles](./people-and-roles.md).
|
||||
immediately. Your Vantage HQ password gets you into it, though the two are kept
|
||||
in step rather than shared. See [People and roles](./people-and-roles.md).
|
||||
|
||||
### Slugs
|
||||
|
||||
The slug becomes your hostname label, so it is lowercase, and some names are
|
||||
reserved. Pick something you can say on a phone call.
|
||||
Your instance's address comes from the name you choose, lowercased, with some
|
||||
names reserved. Pick something short that you can say on a phone call.
|
||||
|
||||
:::warning One Free instance per account, per deployment
|
||||
Creating a second Free cloud instance is refused. If you want another, it needs
|
||||
@@ -41,9 +42,9 @@ affect anyone signing in or any agent syncing.
|
||||
|
||||
Each instance on Overview is one record. Closed, it is a row. Open, it shows:
|
||||
|
||||
- **Licence contents** tier, server allowance, features, expiry.
|
||||
- **Members** who has access and with what instance role.
|
||||
- **Actions** grant access, change configuration, renew.
|
||||
- **Licence contents**: tier, server allowance, features and expiry.
|
||||
- **Members**: who has access, and with what role.
|
||||
- **Actions**: grant access, change configuration, renew.
|
||||
|
||||
## Members
|
||||
|
||||
@@ -53,14 +54,15 @@ Granting access writes a real user into the instance. Covered fully in
|
||||
## Changing what it can do
|
||||
|
||||
Server allowance and per-instance features (browser console, single sign-on) are
|
||||
part of the instance's **entitlement**. Changing it goes through billing see
|
||||
part of the instance's **entitlement**, the configuration your licence is cut
|
||||
from. Changing it goes through billing. See
|
||||
[Licensing and entitlements](./licensing-and-entitlements.md) and
|
||||
[Billing](./billing.md).
|
||||
|
||||
## Renaming
|
||||
|
||||
The display name is free to change. The slug is the hostname and is not
|
||||
casually changed ask support if you need it.
|
||||
The display name is free to change. The slug is part of your hostname, so ask
|
||||
support if you need that changed.
|
||||
|
||||
## What happens if the licence lapses
|
||||
|
||||
@@ -73,6 +75,4 @@ runs to its grace-padded expiry and then lapses.
|
||||
|
||||
## Deleting
|
||||
|
||||
Ask support. Deletion is performed by the control plane, not by HQ the control
|
||||
plane is the only service that knows which collections carry the instance ID,
|
||||
and duplicating that list into HQ would be a list that drifts.
|
||||
Ask support.
|
||||
|
||||
+9
-15
@@ -4,7 +4,8 @@ title: Free tier
|
||||
sidebar_label: Free tier
|
||||
---
|
||||
|
||||
Free is a real tier in both deployments not a trial that turns into nothing.
|
||||
Free is a permanent tier. It is available whether we host Vantage for you or you
|
||||
host it yourself.
|
||||
|
||||
## What you get
|
||||
|
||||
@@ -23,16 +24,15 @@ features on a paid plan.
|
||||
## One per account, per deployment
|
||||
|
||||
The limit is enforced per account **and** deployment. A Free cloud instance does
|
||||
not prevent a Free self-hosted one they are separate slots.
|
||||
not prevent a Free self-hosted one; they are separate slots.
|
||||
|
||||
## Renewing
|
||||
|
||||
Free licences have a term and must be renewed from the portal.
|
||||
Free licences run for a year and are renewed from the portal.
|
||||
|
||||
- The renew button appears **7 days before expiry**.
|
||||
- It stays available **after** expiry, right up until the instance is reaped —
|
||||
so the same button rescues a lapsed instance rather than needing a second
|
||||
mechanism.
|
||||
- It stays available **after** expiry, right up until a lapsed cloud instance is
|
||||
deleted, so the same button rescues one.
|
||||
- Renewing outside that window is refused, and the message names the date it
|
||||
opens.
|
||||
|
||||
@@ -55,19 +55,13 @@ There is no restore. If a cloud Free instance is approaching that date and you
|
||||
want to keep it, renew it, or move it to a paid plan.
|
||||
:::
|
||||
|
||||
Deletion is carried out by the control plane rather than by HQ. HQ sends the
|
||||
warnings because it knows the billing address; the control plane performs the
|
||||
delete because it is the only service that knows which collections carry the
|
||||
instance ID.
|
||||
|
||||
## Moving off Free
|
||||
|
||||
Change the instance's configuration to a paid tier and check out. Your data
|
||||
stays where it is a tier change reissues a licence, it does not rebuild
|
||||
stays where it is: a tier change reissues a licence, it does not rebuild
|
||||
anything.
|
||||
|
||||
## Relinks
|
||||
|
||||
Free instances get the same relink allowance as paid ones: three per term. That
|
||||
cap exists to put a human in front of a fourth attempt, not to obstruct a
|
||||
genuine rebuild.
|
||||
Free instances get the same allowance as paid ones: three relinks per term. If
|
||||
you genuinely need more, ask support.
|
||||
|
||||
@@ -10,7 +10,7 @@ A **licence** is a signed statement of what one instance may do. An
|
||||
## Tiers
|
||||
|
||||
Three tiers, in both deployments. The allowances are identical across cloud and
|
||||
self-hosted what differs is the term on offer, not what you get.
|
||||
self-hosted; what differs is the term on offer, not what you get.
|
||||
|
||||
| | Free | Professional | Enterprise |
|
||||
| --------------------- | --------- | ------------ | --------------------- |
|
||||
@@ -23,17 +23,18 @@ self-hosted what differs is the term on offer, not what you get.
|
||||
|
||||
The server count is **metered**: the base allowance comes with the tier, and you
|
||||
buy additional servers on top. That is why Professional shows a real number
|
||||
rather than "unlimited" the number you actually have is the one in your
|
||||
rather than "unlimited": the number you actually have is the one in your
|
||||
entitlement.
|
||||
|
||||
## Features
|
||||
|
||||
Two are per-instance toggles rather than tier bundles:
|
||||
Three features are enabled per instance rather than bundled into a tier:
|
||||
|
||||
| Feature | What it enables |
|
||||
| --------- | -------------------------------------------------------------------- |
|
||||
| `console` | The [browser console](../vantage/browser-console.md) |
|
||||
| `oidc` | Per-instance [single sign-on](../vantage/settings.md#single-sign-on) |
|
||||
| Browser console | The [browser console](../vantage/browser-console.md) |
|
||||
| Single sign-on | [Sign-in through your identity provider](../vantage/settings.md#single-sign-on) |
|
||||
| Vulnerability scanning| [Package vulnerability scanning](../vantage/vulnerabilities.md) |
|
||||
|
||||
No tier includes them by default; you enable them on the instances that need
|
||||
them.
|
||||
@@ -62,26 +63,35 @@ happens at renewal.
|
||||
|
||||
## What a licence carries
|
||||
|
||||
Instance UUID, deployment, tier, resolved limits, features, term and expiry —
|
||||
all signed.
|
||||
Your instance ID, whether it is cloud or self-hosted, the tier, your limits,
|
||||
which features are enabled, and when it expires. All of it is signed.
|
||||
|
||||
Two properties follow from that:
|
||||
|
||||
- **A licence is bound to one instance UUID.** Moving it takes a
|
||||
[relink](./self-hosted-instances.md#relinking).
|
||||
- **A licence is a snapshot.** Editing a plan later never rewrites an issued
|
||||
licence, the same way editing a workflow step never rewrites a past run.
|
||||
- **A licence works for one instance only.** Moving it to a rebuilt install
|
||||
takes a [relink](./self-hosted-instances.md#relinking).
|
||||
- **A licence is a snapshot.** Changing a plan later does not rewrite a licence
|
||||
already issued.
|
||||
|
||||
Verification is local. Your instance does not call HQ to check a licence, and
|
||||
signing happens only in HQ.
|
||||
|
||||
## Expiry and grace
|
||||
## Expiry, grace and degraded mode
|
||||
|
||||
Expiry is padded with a grace period. Past that, the instance goes into degraded
|
||||
mode: it keeps running and keeps your data, but stops letting you do everything.
|
||||
Expiry is padded with a few days' grace. Past that, an instance goes into
|
||||
**degraded mode**, which means:
|
||||
|
||||
The way out is a current licence renew or purchase, then paste it (self-hosted)
|
||||
or let it be written for you (cloud).
|
||||
- It keeps running, and all of your data stays exactly where it is.
|
||||
- You can still sign in and read everything.
|
||||
- Adding or changing anything is refused.
|
||||
- Deleting things still works, so you can get back under a reduced allowance.
|
||||
- Applying OS updates still works, because security patching is never blocked.
|
||||
|
||||
A brand-new self-hosted install behaves the same way until you install its first
|
||||
licence.
|
||||
|
||||
The way out is a current licence: renew or purchase, then paste it
|
||||
(self-hosted) or let it be written for you (cloud).
|
||||
|
||||
## Server limits in practice
|
||||
|
||||
|
||||
+24
-31
@@ -26,14 +26,11 @@ Owners and admins invite; billing is owner-only.
|
||||
3. They receive a link and set their own password at `/accept-invite`.
|
||||
|
||||
:::info Why you cannot set their password
|
||||
An invitation creates a person with an **empty password hash**, which cannot
|
||||
authenticate at all until they set one. If the inviter chose it, that password
|
||||
would be a shared credential to every instance the person is later granted
|
||||
access to.
|
||||
An invited person cannot sign in at all until they set their own password. If
|
||||
you chose it for them, it would be a shared password to every instance they are
|
||||
later given access to.
|
||||
|
||||
The verification endpoint knows the difference: a token belonging to a
|
||||
passwordless person reports that a password is needed and is left unspent, so
|
||||
the link still works when they get to it.
|
||||
Their invitation link stays valid until they use it to set that password.
|
||||
:::
|
||||
|
||||
### Removing someone
|
||||
@@ -43,26 +40,26 @@ happens to their instance access.
|
||||
|
||||
## Instance access
|
||||
|
||||
Granting access to a **cloud** instance creates a real user inside that
|
||||
instance's control plane, with `auth_source: "hq"`.
|
||||
Granting access to a **cloud** instance creates a real account inside that
|
||||
instance, marked as managed by Vantage HQ.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P["HQ account member"] -->|grant| U["Control-plane user<br/>auth_source: hq"]
|
||||
U --> I["The instance authenticates<br/>this user like any other"]
|
||||
P["Person in your Vantage HQ account"] -->|you grant access| U["Account inside the instance"]
|
||||
U --> I["They sign in at the instance,<br/>like anyone else"]
|
||||
```
|
||||
|
||||
The instance authenticates that user exactly as it authenticates anyone else,
|
||||
with **no runtime dependency on HQ**. Revoking deletes the row the control
|
||||
plane has no disabled state, and a row that exists is a row that can sign in.
|
||||
They then sign in at the instance itself, and that keeps working whether or not
|
||||
Vantage HQ is reachable. Revoking removes the account outright, so access ends
|
||||
immediately.
|
||||
|
||||
### Granting
|
||||
|
||||
On an instance record, **Members → Add**, choose an account member and an
|
||||
instance role (`owner`, `admin`, `member`).
|
||||
|
||||
One person holds at most one user per instance, so granting twice is refused
|
||||
rather than quietly creating a second user.
|
||||
One person gets one account per instance, so granting twice is refused rather
|
||||
than quietly creating a second.
|
||||
|
||||
### Roles inside an instance
|
||||
|
||||
@@ -71,28 +68,24 @@ instance `owner`, or the reverse.
|
||||
|
||||
### Revoking
|
||||
|
||||
Removes the user from the instance immediately. Any live session ends with the
|
||||
session, since the user row backing it is gone.
|
||||
Removes their access immediately, and ends any session they have open.
|
||||
|
||||
:::warning Self-hosted instances cannot be granted from HQ
|
||||
All three member endpoints refuse when the instance is self-hosted. Manage those
|
||||
users in the instance itself, at **Settings → Access**.
|
||||
Vantage HQ cannot add or remove people in a self-hosted install. Manage them in
|
||||
the install itself, at **Settings → Access**.
|
||||
:::
|
||||
|
||||
## Passwords
|
||||
|
||||
Your HQ password is the single source of truth for every user projected from it.
|
||||
Changing it in the portal rehashes it and copies the hash to every instance you
|
||||
have been granted.
|
||||
One Vantage HQ password covers you and every cloud instance you have been given
|
||||
access to. Change it in the portal and it changes everywhere, within about 15
|
||||
minutes at worst if an instance is briefly unreachable.
|
||||
|
||||
Propagation is best-effort and immediate; a background pass compares and repairs
|
||||
every 15 minutes, so a temporarily unreachable instance catches up on its own.
|
||||
|
||||
There is no local password-change endpoint for those users in the control plane,
|
||||
so there is never a second writer for the hash.
|
||||
Those people cannot change that password inside an instance, so there is only
|
||||
ever one place it is set.
|
||||
|
||||
:::warning HQ-managed users are read-only in the instance
|
||||
Changing the role of, or deleting, an `hq`-sourced user inside the control plane
|
||||
is refused with `409`. Do it from the portal. The UI shows those rows read-only
|
||||
with a link back here, but the API is the boundary; the UI is the courtesy.
|
||||
Changing the role of, or removing, someone managed by Vantage HQ has to be done
|
||||
from the portal. Inside the instance those rows are read-only, with a link back
|
||||
here.
|
||||
:::
|
||||
|
||||
@@ -19,54 +19,57 @@ buying in order to build it.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Buy in HQ"] --> B["Placeholder instance<br/>awaiting_link, no licence"]
|
||||
B --> C["Install Vantage<br/>get its instance UUID"]
|
||||
C --> D["Paste the UUID<br/>claim-link"]
|
||||
D --> E["Licence issued<br/>bound to that UUID"]
|
||||
A["Buy in Vantage HQ"] --> B["Placeholder instance<br/>no licence yet"]
|
||||
B --> C["Install Vantage<br/>find its instance ID"]
|
||||
C --> D["Paste your install's ID"]
|
||||
D --> E["Licence issued<br/>for that instance"]
|
||||
```
|
||||
|
||||
1. **Overview → Buy self-hosted**, choose tier, term and configuration.
|
||||
2. Complete checkout. HQ creates a **placeholder** instance in state
|
||||
`awaiting_link` with no licence attached.
|
||||
1. On **Overview**, choose **License my own install**, or **Buy a plan** if you
|
||||
already have an instance. Pick **Self-hosted**, then your tier, billing cycle
|
||||
and configuration.
|
||||
2. Complete checkout. Vantage HQ creates a **placeholder** instance, waiting to
|
||||
be linked, with no licence yet.
|
||||
3. [Install Vantage](../getting-started/self-hosted-install.md) if you have not
|
||||
already, and find its instance UUID at **Settings → Licence**.
|
||||
4. Back in HQ, open the placeholder and paste the UUID.
|
||||
5. The licence is issued, bound to that UUID. Download it and paste it into your
|
||||
install.
|
||||
already, and find its instance ID on the **Licence** page.
|
||||
4. Back in Vantage HQ, open the placeholder and paste that ID.
|
||||
5. The licence is issued. Download it and paste it into your install.
|
||||
|
||||
:::info Why there is a placeholder at all
|
||||
A licence binds to an instance UUID, and at the moment of payment that UUID may
|
||||
not exist yet. Issuing early would mean issuing to nothing; refusing to sell
|
||||
until you had installed would be the wrong order. The placeholder holds the
|
||||
purchase until there is something to bind to.
|
||||
:::info Why there is a placeholder
|
||||
A licence is issued to one instance, and at the moment you pay, that install may
|
||||
not exist yet. The placeholder holds your purchase until it does.
|
||||
:::
|
||||
|
||||
## Linking an existing install
|
||||
## Linking an install you already have
|
||||
|
||||
If the install already exists, **Link an instance** takes the UUID directly. A
|
||||
UUID already claimed by another account is refused with a conflict.
|
||||
If the install exists before the purchase, the flow is the same: buy, then open
|
||||
the placeholder from **Overview**, choose **Link install** and paste its instance
|
||||
ID. An ID already claimed by another account is refused.
|
||||
|
||||
For a Free licence there is no placeholder step. See
|
||||
[Claim a Free licence](../getting-started/claim-free-licence.md).
|
||||
|
||||
## Relinking
|
||||
|
||||
Rebuilding the host produces a new instance UUID, and the old licence no longer
|
||||
matches. **Relink** moves the licence to the new UUID and reissues.
|
||||
Rebuilding the host gives you a new instance ID, which your old licence does not
|
||||
match. **Relink** moves the licence across and reissues it.
|
||||
|
||||
The number of relinks per term is capped, and the portal shows how many you have
|
||||
left. This is not meant to obstruct disaster recovery if you have exhausted
|
||||
them for a real reason, ask support.
|
||||
left. If you have used them all for a genuine reason, ask support.
|
||||
|
||||
## Installing the licence
|
||||
|
||||
Paste it at **Settings → Licence** in your install. The instance verifies the
|
||||
signature and checks that the UUID matches its own.
|
||||
Paste it on the **Licence** page in your install. It confirms the licence was
|
||||
issued to that instance before applying it.
|
||||
|
||||
Pasting works even while the current licence is expired that endpoint is
|
||||
exempt from the licence check, because it is the route out of degraded mode.
|
||||
Pasting works even while your current licence has expired, because that is how
|
||||
you get out of degraded mode.
|
||||
|
||||
## Keeping it current
|
||||
|
||||
Your install does not fetch licences. When a licence is reissued renewal,
|
||||
configuration change, relink download the new one from HQ and paste it in.
|
||||
Your install never downloads a licence by itself. Whenever one is reissued, on
|
||||
renewal, on a configuration change or after a relink, download it from Vantage
|
||||
HQ and paste it in.
|
||||
|
||||
:::warning Nothing reminds your install
|
||||
The control plane knows only what its licence says. Expiry emails come from HQ,
|
||||
|
||||
Reference in New Issue
Block a user