Skip to content
KeystoneOps KeystoneOps Docs

First-run setup wizard

For admins

Setup wizard

Section titled “Setup wizard”

The setup wizard runs once, immediately after a fresh install. It walks the trust’s first admin through the steps needed to get Keystone operational — by the end, every customer-VM-relevant piece of configuration is in place.

When you see it

Section titled “When you see it”
  • Immediately after running curl licensing.../api/install/<token> | sudo bash and the installer prints the Setup URL.
  • The first visit to /setup (with the printed token) renders the first step.
  • The wizard is one-shot — once complete, /setup 404s.

The steps

Section titled “The steps”
  1. Token — paste the installer-printed setup token. Verifies you have legitimate access.
  2. Licence — confirm or paste the licence key. The system phones home to validate.
  3. Workspace — create the first workspace (your trust). Name, slug, default school.
  4. Domain & TLS — set the FQDN (e.g. keystone.trustname.org.uk), choose between Let’s Encrypt and “bring your own certificate”. The wizard applies the nginx + TLS config.
  5. Admin user — create the first admin account. Password policy applies.
  6. Mail — SMTP host + credentials + from-address. Tests by sending a verification email.
  7. SSO — optional. Configure Microsoft 365 / Google Workspace / LDAP at this stage if you want SSO from day one.
  8. Complete — wizard hands you off to the admin shell. From here, you’re in normal operation.

Why the wizard exists

Section titled “Why the wizard exists”

The bash installer doesn’t know your FQDN, your mail server, or your identity provider. It can install the software and start it; it can’t configure the trust-specific bits. The wizard fills that gap with structured input from someone who actually knows the trust’s environment.

What happens if you abandon mid-wizard

Section titled “What happens if you abandon mid-wizard”

Each step persists what you’ve entered, so you can come back and finish later. The wizard remembers where you got to. Until you complete step 8, the install is not in normal operation — sign-in flows route back to /setup.

Gotchas

Section titled “Gotchas”
  • Token security — the printed setup token is sensitive. It’s printed once by the installer and accepted by the wizard. Don’t share it; rotate via php artisan keystone:setup-token if exposed.
  • Domain & TLS — choosing Let’s Encrypt requires the FQDN already pointing at the VM’s public IP. The wizard runs the challenge; a misconfigured DNS makes it fail.
  • Once complete, never repeat — there’s no second-pass. If you need to change FQDN, mail, or SSO later, use the relevant admin pages (/admin/settings/system, /admin/settings/mail, /admin/sso).
Section titled “Related”