Internal draft

Customer self-host

Activate and maintain the deployment license for this install. Spanline issues the seat on Cloud; you bind a signed key to your ServerId.

If you only use Spanline Cloud (no own server), see Cloud organization license instead.

Before you start

Customer server image (default tags — not the Cloud -tags saas control-plane image).
Stable machine identity mounted where the server expects it (typically /etc/machine-id).
A way to reach Spanline to exchange ServerId ↔ signed install key (or a key already signed for your ServerId).
Prefer PostgreSQL + Redis for production; SQLite + in-memory is fine for a smoke install.

First-run setup (every step)

Open the server URL. You land on Set up Spanline. Nothing is written until Finish setup. On self-host with enforce on, the License step is required — you cannot skip it.

Step 1 — Welcome

Setup Welcome step with checklist including required deployment license — Welcome — wizard language and checklist (license called out as required).

Control	What to do
Wizard language	EN or VI for the setup UI
Checklist	Confirms you will set database, cache, admin, optional SSO, deployment license, defaults

Click Continue.

Step 2 — Database

Setup Database step with SQLite and PostgreSQL options — Database — SQLite (quick start) or PostgreSQL (production).

Choice	Fields	Notes
SQLite	Database file path	File/folder created at finish; single node
PostgreSQL	Host, port, database, SSL mode, username, password	Use Test connection before continuing

Step 3 — Cache & queue

Setup Cache and queue step with in-memory and Redis — Cache & queue — in-memory or Redis for Capture storage and live events.

Choice	Fields	Notes
In-memory	—	No extra deps; process-local only
Redis	Redis DSN (e.g. `redis://…`)	Use Test connection; preferred for production / multi-replica

Step 4 — Administrator

Setup Administrator account form — Administrator — first platform admin for this install.

Field	Notes
Username	Required
Display name	Optional
Email	Sign-in identity; defaults to `admin@spanline.dev` if empty
Password / Confirm	At least 8 characters; must match

This account is a platform administrator on this install — not a Spanline Cloud system_admin.

Step 5 — Single sign-on (optional)

Setup SSO optional Google and GitHub credentials — SSO — optional platform Google / GitHub credentials (or skip).

Field	Notes
Google / GitHub Client ID + Client secret	Optional; can also come from env later
Note in UI	Organization SSO (SAML, etc.) is configured later under Organizations → SSO — and org federation is a SaaS story; self-host uses platform social on the login screen

Use Skip for now if you are not ready.

Step 6 — License (required)

Setup License step with ServerId and empty license key — License — copy ServerId, paste signed key, Validate.

Copy the ServerId (srv_…).
Send it to Spanline so they can sign an install key for that ServerId.
Paste the base64 install key.
Click Validate (local check). Phone-home runs when you finish the wizard.

Setup License step after successful Validate — License — after Validate shows customer / expiry before you continue.

You cannot finish setup without a valid key when enforce is on.

Step 7 — Defaults

Setup Defaults timezone and language — Defaults — install timezone and default language (users can override later).

Field	Notes
Timezone	System default
Default language	EN / VI for the install

Step 8 — Review & finish

Setup Review and finish summary — Review & finish — confirm each row (Edit jumps back), then Finish setup.

Check database, cache, admin, SSO, license, defaults.
Click Finish setup. Spanline creates the store, activates the license (phone-home), and leaves setup mode.
Sign in with the administrator email/password you set.

Day-to-day: System → License

After setup, use Platform → System → License (/system/license) on this machine.

System License showing ServerId and active deployment license — System → License — ServerId, current license, replace key.

Block	Use it to…
ServerId	Copy the durable install id for a new signed key
Current license	Confirm customer label, products, limits, expiry
Replace license	Paste a new signed blob (renewal, edition change, re-bind)

System overview with License card on self-host — System overview — License card opens this machine’s license page (self-host only).

Activate / re-activate gate (`/license/active`)

After sign-in, if this machine is not entitled (first bind, expiry, revoke, or machine move), Spanline blocks the product. Who you are decides which screen you see:

Role on this install	Screen
Platform `system_admin`	Activate license — ServerId, paste signed key, Activate
Everyone else	License unavailable — notice to contact the install admin (no paste field)

Admin — Activate license

Activate license gate in a centered setup-style panel with ServerId and license key — Admin re-activate gate (e.g. after clone/move) — centered panel like setup; copy ServerId, paste signed key, Activate.

Control	Action
ServerId	Copy and send to Spanline / your operator
License key	Paste the new signed blob
Activate license	Verifies and phones home
Sign out	Leave without activating

Member — License unavailable

License unavailable notice for non-admin users — Non-admin users see a notice only — they cannot paste a license key.

Typical causes

Cloned VM / new disk → new ServerId (old blob no longer binds)
Seat revoked on Cloud
Machine released on Cloud and not re-signed
Expired seat

Ask Spanline to release the old machine if needed and sign a key for the current ServerId; a system_admin pastes it on the activate gate. See FAQ.

What you will not see on this install

A console to issue seats for other customers
Cloud-only operator tools for managing every tenant’s seats

Surface	When
Account → Installs (on Spanline Cloud)	Your Cloud account was issued a self-host seat — see installs / release machines
Organizations → License	Commercial Cloud org grants only — Cloud organization license. Does not activate this server.

Next: Cloud organization license · FAQ