Setup (setup.ts)

Reference for the SveltyCMS setup and provisioning API — database configuration, schema seeding, and admin creation.

5/25/2026

3 min read

On this page

The Setup API manages the critical initialization phase of SveltyCMS. It handles database configuration, system seeding, and the creation of the primary administrative account.

⚡ Quick Reference

Feature	HTTP Endpoint	Method	Permission Required
Status Check	`/api/setup/status`	`GET`	Public (always)
Test Connection	`/api/setup/test-db`	`POST`	Pre-setup only
Seed Database	`/api/setup/seed-db`	`POST`	Pre-setup only
Complete Setup	`/api/setup/complete`	`POST`	Pre-setup only
Reinitialize	`/api/setup/reinitialize`	`POST`	Administrator session

Note

POST /api/setup/reinitialize is not a grantable permission — it is recovery-only and requires an authenticated administrator session (SETUP_REINIT_FORBIDDEN, src/routes/api/[...path]/handlers/setup.ts). Permission ids elsewhere in the API are authorized fail-closed against ENDPOINT_PERMISSIONS; admin UI tiles use the separate manage:* vocabulary (CONFIG_TILE_PERMISSIONS in src/routes/(app)/config/+page.server.ts) — the two are not interchangeable.

Security Gating: All endpoints except status are protected by isSetupComplete(). After setup finishes, /api/setup/test-db, /api/setup/seed-db and /api/setup/complete all return 403 SETUP_ALREADY_COMPLETE; /api/setup/reinitialize returns 403 SETUP_REINIT_FORBIDDEN unless the caller is a real administrator session. This is enforced at two levels: the handleSetupRoutes handler entry check, and the handle-system-state.ts middleware. See Server Hooks.

1. The Goal

Safely transition a fresh SveltyCMS installation from an unconfigured state to a production-ready environment by establishing a database connection and provisioning the first user.

2. The Solution

Pre-flight Verification

Before persisting the configuration, the system validates the provided database credentials.

Endpoint: POST /api/setup/test-db Payload:

{
  "type": "mongodb",
  "host": "localhost",
  "port": 27017,
  "database": "sveltycms",
  "username": "...",
  "password": "...",
  "directConnection": true
}

Schema Provisioning

Triggers the creation of system collections, default roles, and internal configuration entries.

Endpoint: POST /api/setup/seed-db

Finalization

The setup process concludes by creating the admin user and establishing their first session. Once successful, the system is marked as ready, and all setup endpoints (except status) are strictly blocked with 403.

3. The Mechanics

Pre-Boot Architecture

The setup.ts handler operates in a standalone mode, allowing it to function before the primary database adapter and middleware are fully initialized.

sequenceDiagram
    participant User as Admin Wizard
    participant API as Setup Handler
    participant FS as config/private.ts
    participant DB as Database Engine

    User->>API: POST /seed-db
    API->>FS: writePrivateConfig()
    API->>DB: Build Collections & Roles
    API-->>User: 200 OK (Seeding Started)

Documentation