This page is the operator’s path through first-run setup: what to prepare, what each of the six steps asks for, how to confirm it worked, and what to do when a step fails. The short version is the setup walkthrough and install commands are Getting started. How the installer itself works — its phases, the config it writes, and the boot that follows — is Boot and initialization.

The SveltyCMS setup wizard provides a professional, multi-step configuration experience with real-time validation, intelligent error handling, and a modern user interface.

Table of Contents

• Overview
• Features
• Setup Steps
• Solution Presets
• Error Handling
• User Experience
• Troubleshooting

Overview

The setup wizard is a multi-step form that guides users through initial SveltyCMS configuration. It consists of 6 main steps:

1. Database Configuration - Database connection and testing, optional Redis caching, and optional read replicas
2. Admin Account - Administrator user creation
3. Project Blueprint - Starting blueprint, plus the market (country, currency, tax) for a shop
4. System Settings - Site identity, languages, media storage, infrastructure mode, and Cloudflare CDN purging
5. Email Configuration (Optional) - SMTP setup for notifications
6. Review & Complete - Final review and system initialization

Before you start

• A target database — or none at all. SQLite needs only a writable path. For MongoDB, PostgreSQL, MySQL, or MariaDB, have host, port, and database name ready, plus a user and password for every type except plain mongodb.
• The production URL the install will serve, for example https://cms.example.com.
• The administrator account: username, email, and a password that meets the rules in Step 2.
• SMTP details if the CMS should send mail — optional, and changeable later in settings.
• A willingness to overwrite an existing database. If the target already contains tables, the wizard detects that and asks before it drops anything.

Setup Wizard Flow

Quick Stats

• Total Steps: 6 (5 required + 1 optional)
• Real-time Validation: All input fields
• Auto-save: localStorage persistence
• No server restart required: the system becomes operational immediately after setup completion

Features

Real-Time Validation

Every input field provides instant feedback using Valibot schemas:

• ✅ Client-side validation as users type
• ✅ Server-side validation on submission
• ✅ Field-specific error messages
• ✅ Visual error indicators (red borders, error text)

Intelligent Error Handling

The wizard includes comprehensive error management:

• Database Test Errors: Detailed classification (auth failed, connection timeout, etc.)
• Validation Errors: Per-field and per-step error tracking
• Network Errors: Graceful handling with retry options
• Loading States: Visual feedback during async operations

User Experience Enhancements

Modern UX features inspired by best practices:

• Progress Indicator: Visual step tracker (mobile horizontal, desktop vertical)
• Unsaved Changes Warning: Browser warning before navigation
• Duplicate Submission Prevention: isSubmitting guard
• Auto-save: Form data persists in localStorage
• Step Navigation: Click completed steps to review/edit
• Responsive Design: Optimized for mobile, tablet, and desktop

Accessibility

WCAG 2.1 AA compliant features:

• Semantic HTML with proper roles and ARIA labels
• Keyboard navigation support
• Screen reader friendly
• Error announcements via role="alert"
• High contrast mode compatible

Setup Steps

Step 1: Database Configuration

Purpose: Configure and test database connection

fields:

• Database Type (SQLite, PostgreSQL, MariaDB/MySQL, MongoDB, MongoDB Atlas)
• Host/Connection String
• Port (for non-Atlas)
• Database Name
• Username (required for PostgreSQL, MariaDB/MySQL and mongodb+srv, optional for a local MongoDB)
• Password (same rules as the username)
• Redis caching (optional): when enabled, Redis host, port, and password, plus a Test Redis Connection button
• Advanced Database Options (Clustering & Scaling) (optional): full connection strings for regional read-only replicas (PostgreSQL and MongoDB), one per replica, with an optional ?region=code suffix for geo routing

Features:

• Connection String Parsing: Paste full MongoDB URI, automatically extracts credentials
• Driver Installation on Test: MongoDB and SQLite drivers ship with the CMS; for the other types the wizard installs the driver through the detected package manager when you click Test Connection
• Atlas Helper: Collapsible guide for MongoDB Atlas setup
• Existing Data Detection: Probes the target database for existing tables or collections before proceeding.
• Data Overwrite Confirmation: If existing data is detected, the wizard provides a clear modal warning. Users can choose to Overwrite the database (which drops and recreates it) or specify different connection details to prevent accidental data loss.
• Test Connection: Validates configuration before proceeding
• Error Classification: Detailed error messages (auth failed, timeout, DNS error, etc.)

Validation Rules:

• Host is required and non-empty
• Database name is required, and may contain letters, numbers, hyphens, underscores, and dots
• Port must be a number between 1 and 65535 (not required for Atlas)
• Username and password are required for PostgreSQL, MariaDB/MySQL and mongodb+srv
• Credentials validated on test

Redis caching (optional):

Redis lives on this step because it caches database queries and session data.

• An Enable Redis Caching checkbox carries a help tooltip explaining what it does.
• Enabling it reveals host, port, and password fields plus a Test Redis Connection button.
• The test is optional; the check is not. Enabling Redis without a passing test blocks Next, and the wizard shows a toast telling you to test the connection first.
• The connection values are written to the database settings on completion — not to config/private.ts.

Advanced Database Options (Clustering & Scaling) (optional):

An expandable section, with a help tooltip, that collects full connection strings for regional read-only replicas (PostgreSQL and MongoDB).

• One connection string per replica, added with Add Replica Node and removed with the row’s close button.
• Append ?region=code to a string for geographic routing, for example postgresql://user:pass@replica-host:5432/db?region=us-east.
• This field is collected for a future, opt-in read-replica setup. It is not required, and the wizard does not persist these values. Read replicas are configured at runtime through the DB_REPLICA_URLS System Setting (or the DB_REPLICAS environment variable) after setup.

These are three separate scaling layers: Redis caches database queries in memory, the database read replicas above offload read queries to additional databases, and the Cloudflare purge on Step 4 invalidates the CDN’s edge HTTP cache. They are not the same mechanism.

Server calls: testDatabaseConnection, installDatabaseDriver, and testRedisConnection (remote functions in src/routes/setup/setup.remote.ts); the database test logic is also exposed as the testDatabase form action.

Success Criteria:

• Green success message with connection details
• “Next” button enabled
• Seeding has already started in the background: the wizard writes config/private.ts and seeds settings, roles, and themes while you fill in the remaining steps
• Editing the connection fields after a green test hides the success summary and asks for another test — the check always applies to the connection you are about to use

stateDiagram-v2
    [*] --> EnterConfig: User fills form
    EnterConfig --> TestConnection: Click "Test Connection"
    TestConnection --> Installing: Missing driver?
    Installing --> TestConnection: Driver installed
    TestConnection --> Success: Connection OK
    TestConnection --> Failed: Connection failed
    Failed --> EnterConfig: Fix errors
    Success --> NextStep: Click "Next"
    NextStep --> [*]

Step 2: Admin Account Creation

Purpose: Create the first administrator user

fields:

• Username (2-50 characters: letters, numbers, and @ $ ! % * # . _ -)
• Email (valid email format)
• Password (8+ chars with complexity requirements)
• Confirm Password (must match)

Features:

• Password Requirements Indicator: Visual checklist showing:
  • ✓ Minimum 8 characters
  • ✓ At least one letter (A-Z or a-z)
  • ✓ At least one number (0-9)
  • ✓ At least one special character (@$!%*#?&)
  • ✓ Passwords match
• Password Visibility Toggle: Eye icon to show/hide passwords
• Real-time Validation: Instant feedback on each requirement

Validation Rules:

• Username: 2-50 characters, letters, numbers and @ $ ! % * # . _ - only
• Email: Valid email format
• Password: 8+ chars with uppercase, lowercase, number, special char
• Confirm password must match password

Server calls: None (validated in the step; sent to completeSetup when you finish)

Success Criteria:

• All password requirements met
• No validation errors
• “Next” button enabled

Step 3: Project Blueprint

Purpose: Choose the starting blueprint and, for a shop, the market defaults

fields:

Project Blueprint:

• The preset carousel described in Solution Presets. Seven cards: Blank, Website Starter (recommended default), Blog / Editorial, Agency / Portfolio, SaaS Product, Corporate Site, and E-commerce. Each card lists the collections it creates.

Country and prices — shown only when the E-commerce blueprint is selected:

• Country, or “Choose later”
• Currency (ISO 4217) and shop language (English or German)
• Whether catalog prices already include tax
• Standard and reduced tax percents. The form fills a suggestion checked on 5 October 2026. Clear the standard rate, or leave the country empty, and the shop seeds no tax row

Features:

• Blueprint Carousel: Browse and pick one starting preset; the selection is stored as the preset setting.
• Market Gating: The Country and prices block appears only for the ecommerce blueprint, because country, currency, and tax data only matter for a shop. It is hidden for every other blueprint.
• Suggested Market Data: Picking a country fills currency, shop language, and suggested tax rates, and every value stays editable.
• Collections at Completion: The selected blueprint’s collections are written when you complete the wizard, not earlier.

Validation Rules:

• A blueprint must be selected

Server calls: None (the preset id is sent to completeSetup when you finish). Tax and shipping rows are seeded only for the E-commerce preset (seedEcommerceDefaults in setup.server.ts).

Success Criteria:

• A blueprint is selected
• “Next” button enabled

Step 4: System Settings

Purpose: Configure site identity, language settings, media storage, and infrastructure

fields:

Basic Settings:

• Site Name (e.g., “My SveltyCMS Site”)
• Production URL (full URL with https://)
• Timezone

Language Configuration:

• Default System Language (admin interface language)
• System Languages (available UI languages)
• Default Content Language (default for created content)
• Content Languages (available content languages)

Media Storage:

• Storage Type (Local, S3, R2, Cloudinary)
• Storage Path/Bucket Name (a folder path for Local, or a bucket/cloud name for the cloud types)

Advanced: Enterprise Scaling (Cloudflare CDN) — collapsible, collapsed by default:

• Toggled with a chevron in the heading. It expands automatically when a cloud media storage type (Amazon S3, Cloudflare R2, or Cloudinary) is selected above.
• Cloudflare API Token — with a help tooltip
• Cloudflare Zone ID — with a help tooltip
• Purge Strategy — with a help tooltip
• This purges the Cloudflare edge cache when content changes, so visitors get fresh pages immediately. It is a different layer from the database read replicas in Step 1: this is edge/CDN HTTP cache invalidation, not read-query offloading.
• When a cloud media storage type is selected in the Media Storage section above, a notice renders to the right of this heading: “Cloud storage credentials must be configured in System Settings after setup.” Select Local and the notice disappears.

Infrastructure Mode:

• Multi-Tenant Mode
• Demo Mode (warns that data is wiped automatically; do not enable on production)

Features:

• Smart Language Presets: Auto-detects browser language
• Chip-based UI: Visual chip display for selected languages
• Language Search: Quick filter for adding languages
• Dual Language System:
  • System Languages: Same ISO 639-1 picker as content. English and German ship compiled. Extra codes are written to project.inlang/settings.json and machine-translated (bun translate) when setup completes. RTL languages use getTextDirection() in @utils/string.
  • Content Languages: From ISO-639-1 (150+ languages), no rebuild required.
• Cloud Storage Notice: When a cloud media storage type is selected, a notice appears beside the Cloudflare CDN heading reminding you to configure the credentials in System Settings after setup
• Collapsible CDN Section: The Cloudflare purge fields sit behind a chevron toggle, collapsed by default and expanded automatically for a cloud media storage type. The section and each of the three field labels carry a help tooltip

Validation Rules:

• Site name is required
• Production URL must be valid URL with protocol
• At least one system language required
• At least one content language required
• Default languages must be in their respective arrays

Server calls: None (validated in the step and sent to completeSetup when you finish)

Success Criteria:

• All required fields filled
• Valid URL format
• Language configuration valid
• “Next” button enabled

Step 5: Email Configuration (Optional)

Purpose: Configure SMTP for email notifications

fields:

• SMTP Host (e.g., smtp.gmail.com)
• SMTP Port (587 for TLS, 465 for SSL)
• Username/Email
• Password/App Password
• From Address (sender email)
• Use TLS (checkbox)

Features:

• Provider Presets: Quick setup for Gmail, Outlook, SendGrid
• Test Email: Send test email to verify configuration
• Skip Option: Can be configured later in settings
• Collapsible: Step can be collapsed/expanded

Validation Rules:

• Host is required (if configuring)
• Port must be valid number
• Username and password required (if configuring)
• From address must be valid email

Server call: testEmailConnection (remote function in src/routes/setup/setup.remote.ts) for the test email

Success Criteria:

• Test email sent successfully (if configuring)
• OR step skipped (optional)
• “Next” button always enabled

Step 6: Review & Complete

Purpose: Review all settings and finalize setup

Display:

• ✅ Database configuration summary
• ✅ Admin account details (password hidden)
• ✅ Project blueprint summary
• ✅ System settings summary
• ✅ Email configuration status

Features:

• Edit Links: Click any section to return to that step
• Final Validation: Re-validates all steps before submission
• Loading State: Shows progress during initialization
• Preset Collections: The blueprint you picked in step 3 is written to config/collections (config/{tenant}/collections in multi-tenant mode) and registered here, not earlier
• Auto-login: Creates the session cookie on success (24-hour session)
• Smart Redirect: Lands on the first seeded collection, or /login when there is none to open
• Re-run Guard: If the database already holds an administrator, completion is refused rather than overwriting it

Server call: completeSetup (remote command in src/routes/setup/setup.remote.ts), also exposed as the completeSetup form action

📦 Solution Presets (Starter Kits) {#solution-presets-starter-kits}

Presets are pre-configured collections of schemas, widgets, and settings designed for specific use cases. You choose one in the Project Blueprint carousel on Step 3; the collections are created when you complete the wizard, and the preset id is stored as a setting.

Available Presets

Each card lists the collections that preset creates (src/routes/setup/presets.ts). A card does not add core features such as the media library, audit log, or multi-tenant mode — those are available on every install.

1. Blank Project

• Best for: Custom builds, headless-first installs.
• Includes: Minimal configuration. No collections.

2. Website Starter

• Recommended default.
• Best for: A SvelteKit frontend in the same repo with inline page design.
• Includes: pages, a seeded homepage, a legal page named for the market country (Impressum with the default Germany), and a privacy page for the operator to complete. Live preview and the Editable Website plugin turn on when setup finishes.

3. Blog / Editorial

• Best for: Content-heavy sites, news portals.
• Collections:
  • posts: Rich text, SEO, a relation to authors, categories, and tags.
  • categories: Name, slug, and an optional parent category.
  • authors: Name, bio, avatar, and email.

4. Agency / Portfolio

• Best for: Design agencies, freelancers, creative studios.
• Collections:
  • projects: Description, client name, images, and a testimonial.
  • services: Name, description, and a feature list.
  • team: Role, bio, photo, and profile links.

5. SaaS Product

• Best for: Software companies, product landing pages.
• Collections:
  • pricing: Gross price, currency (default EUR), interval (month, year, or once), and a feature list. This is a published plan, not a checkout.
  • features: Name, description, and a screenshot.
  • documentation: Title, slug, body, category text, and sort order.

6. Corporate Site

• Best for: Business websites, company profiles.
• Collections:
  • team: Name, position, bio, photo, and department.
  • careers: Title, department, location, description, and requirements. The location is a field on the job.
  • press: Title, date, source, URL, and excerpt.

7. E-commerce

• Best for: Online stores, catalogs.
• Collections: products (variants with own SKU/price/inventory), product_categories, product_reviews, coupons, tax_rates, shipping_zones, carts, orders.
• Import: Smart Importer maps WooCommerce (WXR/REST) or Shopify JSON/CSV into products.
• Dashboard: add Commerce Orders and Commerce Inventory widgets (freemium, 14-day trial) from the dashboard picker.
• Map: E-Commerce Overview — preset, importer, dashboard widgets, checkout pipeline, Stripe.

Error Handling

Error Categories

1. Validation Errors

Source: Client-side or server-side validation

Display:

• Red border on input field
• Error message below field
• Icon indicator in step tracker

Example:

❌ Email is required
❌ Password must be at least 8 characters
❌ Passwords do not match

2. Network Errors

Source: Failed API calls

Display:

• Error toast notification
• Detailed error message in expansion panel
• Retry button

Example:

❌ Network error: Failed to fetch
💡 Check your internet connection and try again

3. Database Errors

Source: Database connection test failures

Display:

• Detailed error block with:
  • User-friendly message
  • Technical error code
  • Connection details
  • Suggested fixes

Error Classifications (from src/routes/setup/error-classifier.ts):

• AUTH_FAILED - Invalid credentials for this database user.
• CONNECTION_REFUSED - Cannot reach the server: down, wrong host, timed out, or your IP is not allowlisted.
• DB_NOT_FOUND - The database does not exist. The wizard offers to create it.
• DB_ALREADY_EXISTS - The database already contains tables; the wizard asks before overwriting.
• CASE_MISMATCH - A database with the same name in a different case exists; reuse the existing name or overwrite.
• INVALID_CONFIG - Malformed connection string, or an SSL/TLS handshake failure.
• Anything unmapped arrives as Database connection failed: <message> with the server log as the next step.

Example:

❌ Connection Failed

Error: Authentication failed. Please check your username and password.

Connection Details:
- Host: cluster0.mongodb.net
- Port: 27017
- Database: sveltycms
- User: admin
- Code: authentication_failed

💡 Suggested Fix:
- Verify your MongoDB Atlas username and password
- Check if IP address is whitelisted in Atlas
- Ensure database user has correct permissions

4. Driver Installation Errors

Source: Failed automatic driver installation

Display:

• Warning box with installation status
• Manual installation instructions
• Continue anyway option

Example:

⚠️  Driver Installation Failed

The MongoDB driver could not be installed automatically.

Error: npm install mongoose failed (network timeout)

You can:
1. Install manually: npm install mongoose
2. Check your internet connection
3. Continue with setup (connection test will fail until installed)

How the wizard classifies these errors, and how its validation layers are built, is in Boot and initialization.

User Experience

Loading States

Visual Indicators:

• Spinner icon during async operations
• Disabled buttons to prevent double-clicks
• “Loading…” or “Testing…” text
• Progress messages (“Initializing system…“)

Toast Notifications

Types:

• Success (green): a step succeeded, e.g. “Setup complete! Redirecting…”
• Error (red): a failed test, seed, or completion
• Info (blue): a notice while longer work runs
• Warning (yellow): a non-blocking problem

Position: Bottom-right corner (fixed)

Duration:

• Success: 2 seconds on completion
• Error: 5 seconds for a failed completion, 4 seconds for a failed seed, 8 seconds when setup is already complete
• Info/Warning: 4 seconds by default

Responsive Design

Breakpoints:

• Mobile: < 640px (sm)
• Tablet: 640px - 1024px (md)
• Desktop: > 1024px (lg)

Adaptations:

Mobile:

• Horizontal step indicator (dots)
• Single column form layout
• Stacked language selector
• Collapsible help text
• Full-width buttons

Desktop:

• Vertical step indicator (with descriptions)
• Two-column form layout
• Side-by-side language configuration
• Expanded help text
• Inline action buttons

CSS Pattern:

/* Mobile-first approach */
.form-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1.5rem;
}

/* Tablet and above */
@media (min-width: 768px) {
  .form-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

Keyboard Navigation

Shortcuts:

• Tab / Shift+Tab - Navigate between fields
• Enter - Submit current action (test connection, next step)
• Escape - Close language picker or help popups
• Arrow keys - Navigate step indicator (desktop)

Focus Management:

• Auto-focus first field on step change
• Visible focus indicators
• Skip links for screen readers
• Focus trap in modals

Troubleshooting

Common Issues

Issue: Database Test Fails with “Driver Not Found”

Symptoms: Error about missing mongoose package

Cause: The driver install that runs with Test Connection failed (network, permissions) or was skipped

Solution:

# Manual installation
npm install mongoose
# or
bun add mongoose
# or
pnpm add mongoose

Then clear localStorage and retry test. MongoDB and SQLite drivers ship with the CMS, so this only affects PostgreSQL, MySQL, and MariaDB (postgres, mysql2).

Issue: A Step Will Not Let Me Continue

Symptoms: “Next” stays disabled

Cause and fix, by step:

• Step 1: there is no connection test yet for the current values. Editing host, port, name, user, or password after a green result clears it — press Test Connection again. There is no automatic retry: fix the reported cause first. If Redis is enabled, it also needs a passing Test Redis Connection.
• Step 2: one of the password requirements is unmet, or the two passwords differ.
• Step 3: no blueprint is selected.
• Step 4: site name or production URL missing, or no language selected.
• Step 6: seeding is still running; the button enables when it finishes.

Issue: Setup Refuses to Finish Because Administrators Exist

Symptoms: Completion returns “Database contains registered administrator accounts. Setup cannot be re-run.”

Cause: The target database already holds an admin user, so the wizard will not overwrite it

Solution: Point the wizard at a fresh database and name, or remove the existing administrators yourself if you really intend to re-run first-run setup.

Issue: Collections Are Missing or the Wizard Keeps Returning to /setup

These are boot-time conditions rather than wizard steps: see the troubleshooting in Boot and initialization.

Related Documentation

• Setup Reference - Complete API documentation
• Boot and initialization - Installer phases, generated config, and restart behavior
• Valibot Documentation - Validation library
• Svelte 5 Runes - Reactive state management

Best Practices

For Users

1. Test Database Connection First - Always test before proceeding
2. Use Strong Passwords - Follow all password requirements
3. Note Your Credentials - Save admin username/password securely
4. Complete All Steps - Don’t skip system settings
5. Review Before Completing - Check all settings on final step

Summary

The SveltyCMS setup wizard provides a professional, user-friendly onboarding experience with:

✅ Real-time validation with Valibot ✅ Intelligent error handling and recovery ✅ Persistent state with auto-save ✅ Responsive design for all devices ✅ Accessibility features (WCAG 2.1 AA) ✅ One blueprint, and the collections that card lists ✅ Website Starter seeds Home, a country legal page, and Privacy ✅ No-restart initialization

What happens underneath — the installer phases, the generated config/private.ts, and the boot that follows — is in Boot and initialization.