Setup Wizard

Setup Wizard

The Setup Wizard is the first-run onboarding flow every new Piro instance goes through, from an empty database to a ready-to-use owner account. It runs once — as soon as an owner account exists, visiting the admin panel skips straight to sign-in.

Overview

When the admin panel (apps/admin) detects that setup has not been completed (GET to the setup status endpoint returns IsComplete: false), it redirects to the wizard instead of the sign-in page. The wizard is a single page with three sequential steps, followed by a one-time feature tour on first login.

Source: SetupController.cs, SetupPage.tsx

The three steps

Step 1 — General

Field	Description
Site name	Required. Shown on the public status page and in emails
Site URL	Optional. The public URL of your instance

Step 2 — Account

Creates the owner account.

Field	Description
Full name	Required
Email	Required — becomes the owner's login and the recipient of the verification code in Step 3
Password	Required, minimum 8 characters
Confirm password	Must match
Time zone	Required. Defaults to the value detected from the browser (Intl.DateTimeFormat().resolvedOptions().timeZone), overridable from a picker. This becomes the owner's personal display timezone used everywhere dates/times are shown in the admin panel

Step 3 — Email (required)

Unlike the previous two steps, Email cannot be skipped. You must configure a working email provider and verify it with a one-time code before setup can complete.

Field	Description
Provider	smtp or resend
SMTP: Host, Port, Username, Password, From, Use SSL	Standard SMTP connection settings
Resend: API Key, From	Resend API configuration as an SMTP alternative
Verification code	6-digit code sent to the owner's email once the configuration above is submitted

To finish this step:

1. Fill in your SMTP or Resend configuration and request a code — Piro sends a 6-digit verification code to the owner's email address using that exact configuration.
2. Enter the code to confirm delivery works.
3. Complete setup.

⚠️ The verification code is stateless. It's an HMAC-SHA256 code bound to the exact email configuration you submitted — not stored in any database or cache. If you change any SMTP/Resend field after requesting a code, the pending code is invalidated and you must request a new one.

Why email is mandatory

Older versions of Piro let you skip email configuration and add it later. This is no longer allowed — email is the fallback delivery channel that guarantees on-call notifications, alert triggers, and team member invitations work from the moment the instance exists, not "eventually, once someone remembers to configure SMTP." Making it mandatory at setup closes a common gap where a newly self-hosted instance silently has no working notification path.

If the verification code doesn't arrive

1. Check spam/junk folders — transactional email from a new SMTP host is a common spam trigger.
2. Double-check host and port — a wrong port (e.g. 465 with Use SSL off, or 587 with it on) is the most common misconfiguration.
3. Confirm credentials — an invalid username/password on some SMTP providers fails silently rather than returning a clear error.
4. Use "Resend code" — safe to retry; each request generates a fresh HMAC code tied to the current form values.
5. If using Resend, confirm the From address's domain is verified in your Resend account — unverified domains silently fail to deliver.

Feature showcase

Immediately after the first successful login following setup, Piro shows a full-screen, one-time feature tour — a guided walkthrough of the product before the user lands on the empty dashboard.

• 8 slides: Welcome, Services, Checks, Alerts, On-call & Escalation, Incidents, Maintenances, and a closing slide.
• Navigation: manual only — arrow controls plus a clickable progress bar to jump between slides. It does not auto-advance.
• Skip: always visible; dismissing it at any point marks the tour as seen.
• Persistence: tracked per-user via AppUser.HasSeenShowcase — it will not reappear for that user once dismissed or completed, even across sessions. New users created later (e.g. via invitation) get their own first-time showcase.

Related

• Environment Variables — email requirement notes
• Development Setup — running the wizard locally
• Notification Preferences — personal channels configured after setup