Setup Wizard

The setup wizard provides the first-time configuration flow in CARE and is implemented in frontend/src/auth/SetupWizard.vue.

When it is used

The wizard is shown for fresh instances where no admin account exists. Instead of going directly to login, the user is guided through setup and then redirected to the regular application flow.

Backend endpoints used by this flow:

  • GET /setup/config: fetch steps (key, title, description, order, typeId), wizardStepTypes (id, key), wizard settings, and full settings snapshot.

  • POST /auth/setup-admin: create the initial admin account.

  • POST /setup/test-mail: send a test mail during setup.

  • POST /setup/complete: persist setup settings and mark setup as completed.

Wizard Steps

The current step sequence is:

  1. Admin (create first admin account)

  2. General (base app behavior)

  3. Mail (mail service and provider fields)

  4. Registration (registration and consent-related settings)

  5. Summary (final review and save)

Note

Moodle-related wizard settings are currently grouped under General via subsection metadata.

Frontend components

Step components live under frontend/src/components/wizard/.

  • SetupWizardAdminStep.vue: create the first admin account

  • SetupWizardGeneralStep.vue: general settings and Moodle block

  • SetupWizardMailStep.vue: mail service, provider fields and send test email

  • SetupWizardRegistrationStep.vue: registration and consent fields

  • SetupWizardSummaryStep.vue: review and finish

SetupWizard.vue keeps formData for the admin account fields and formSettings for all other setting values edited in the wizard. wizardSettings supplies display names and subsection grouping for the settings and summary steps. Credential changes use update-admin-field; setting field changes run through setWizardSettingValue. Navigation, JSON import, and test mail use additional events on the parent.

How Settings Are Rendered

Wizard fields come from setting metadata in the database. For the setup flow and the dashboard settings rework to stay aligned, settings should define:

  • displayName

  • displayGroup

  • displaySubsection

  • showInWizard

  • wizardStep

  • wizardOrder

  • requiredInWizard

For details and migration examples, see Settings.

Import and Export

The wizard supports JSON import/export to simplify migration from an existing CARE instance.

  • Download exports a JSON snapshot based on loaded settings plus current wizard form values.

  • Import accepts key/value JSON and normalizes values to strings for settings persistence.

  • Imported keys are validated against known setting keys from /setup/config.

  • Unknown keys are ignored and reported in toast feedback.

  • After successful import, the wizard moves to Summary for review before finishing.

Mail Test During Setup

The mail step includes a test action that calls POST /setup/test-mail with the current mail configuration and recipient address.

This allows validating SMTP/sendmail setup before finishing setup.

Extending the Wizard

To add or change setup fields:

  1. Add/update setting rows via migration (including wizard and display metadata).

  2. Ensure the new keys are returned by /setup/config.

  3. If needed, update step-specific rendering in frontend/src/components/wizard/ and orchestration logic in frontend/src/auth/SetupWizard.vue.

  4. Verify import/export behavior for the new keys.

To change the setup order or visible steps:

  • Update wizard step definitions returned by /setup/config.

  • Keep frontend step filtering consistent with dependency rules.