Skip to content

Configuration_API.mdx

Latest commit

 

History

History
734 lines (531 loc) · 11.4 KB

Configuration_API.mdx

File metadata and controls

734 lines (531 loc) · 11.4 KB
Raw
path docs/api/Configuration_API.mdx
title Configuration & Setup API
description Complete API reference for system configuration, setup, and database management in SveltyCMS.
order 10
icon mdi:cog
author admin
created 2025-10-05
updated 2025-10-05
tags
api
configuration
setup
admin

Configuration & Setup API

Overview

The Configuration API provides endpoints for system setup, database configuration, and system maintenance. These endpoints are primarily used during initial setup and system administration.

Base Paths:

  • /api/config/* - Configuration management
  • /api/setup/* - Initial setup

Setup Endpoints

1. Test Database Connection

Tests database connection settings before saving.

Request

POST /api/setup/test-database

Headers:

Content-Type: application/json

Body:

{
	"DB_TYPE": "mongodb",
	"DB_HOST": "localhost",
	"DB_PORT": 27017,
	"DB_USER": "admin",
	"DB_PASSWORD": "password",
	"DB_NAME": "sveltycms"
}

Database Types:

  • mongodb - MongoDB or MongoDB Atlas
  • mariadb - MariaDB/MySQL
  • postgresql - PostgreSQL (future)

Permissions Required: Setup mode or admin

Response

Success (200):

{
	"success": true,
	"message": "MongoDB connection successful!",
	"details": {
		"host": "localhost",
		"port": 27017,
		"database": "sveltycms",
		"version": "6.0.0",
		"latency": 12
	}
}

Error Responses:

// 400 Bad Request - Connection failed
{
  "success": false,
  "message": "MongoDB connection failed: Authentication failed",
  "errorType": "authentication",
  "suggestions": [
    "Check username and password",
    "Verify user has correct permissions",
    "Ensure auth database is correct"
  ]
}

// 400 Bad Request - Invalid configuration
{
  "success": false,
  "message": "Invalid database configuration",
  "errors": [
    "DB_HOST is required",
    "DB_PORT must be a number"
  ]
}

Error Classification:

The endpoint classifies errors and provides helpful suggestions:

  • Authentication - Wrong credentials
  • Network - Can't reach database
  • Authorization - User lacks permissions
  • Configuration - Invalid settings
  • Driver - Missing database driver

2. Install Database Driver

Automatically installs missing database drivers.

Request

POST /api/setup/install-driver

Headers:

Content-Type: application/json

Body:

{
	"databaseType": "mongodb"
}

Permissions Required: Admin or setup mode

Response

Success (200):

{
	"success": true,
	"message": "Database driver installed successfully",
	"package": "mongoose",
	"version": "8.0.0",
	"output": "Successfully installed mongoose@8.0.0"
}

Detects Package Manager:

  • Bun (if bun.lock exists)
  • Yarn (if yarn.lock exists)
  • pnpm (if pnpm-lock.yaml exists)
  • npm (default)

3. Seed Settings

Seeds initial system settings into the database.

Request

POST /api/setup/seed-settings

Headers:

Cookie: session=your-session-id
Content-Type: application/json

Body:

{
	"tenantId": "default-tenant",
	"overwrite": false
}

Permissions Required: Admin

Response

Success (200):

{
	"success": true,
	"message": "Settings seeded successfully",
	"seeded": {
		"system": 15,
		"theme": 8,
		"security": 12
	},
	"total": 35
}

4. Complete Setup

Marks initial setup as complete.

Request

POST /api/setup/complete

Headers:

Cookie: session=your-session-id

Permissions Required: Admin or setup mode

Response

Success (200):

{
	"success": true,
	"message": "Setup completed successfully",
	"timestamp": "2025-10-05T14:30:00Z"
}

Side Effects:

  • Disables setup mode
  • Redirects to admin dashboard
  • Logs setup completion

Configuration Endpoints

1. Save Configuration

Saves system configuration to file.

Request

POST /api/config/save-config

Headers:

Cookie: session=your-session-id
Content-Type: application/json

Body:

{
	"config": {
		"DB_TYPE": "mongodb",
		"DB_HOST": "localhost",
		"DB_PORT": 27017,
		"DB_NAME": "sveltycms",
		"SITE_NAME": "My CMS",
		"SITE_URL": "https://cms.example.com"
	}
}

Permissions Required: Admin

Response

Success (200):

{
	"success": true,
	"message": "Configuration saved successfully",
	"file": ".env",
	"timestamp": "2025-10-05T14:30:00Z"
}

Security:

  • Sensitive values encrypted
  • File permissions set to 600
  • Backup created before save

2. Load Configuration

Loads current system configuration.

Request

GET /api/config/load

Headers:

Cookie: session=your-session-id

Permissions Required: Admin

Response

Success (200):

{
	"success": true,
	"config": {
		"DB_TYPE": "mongodb",
		"DB_HOST": "localhost",
		"DB_PORT": 27017,
		"SITE_NAME": "My CMS",
		"SITE_URL": "https://cms.example.com",
		"MULTI_TENANT": true,
		"CACHE_ENABLED": true
	},
	"masked": ["DB_PASSWORD", "JWT_SECRET", "ENCRYPTION_KEY"]
}

Note: Sensitive values are masked for security

3. Backup Configuration

Creates a backup of current configuration.

Request

POST /api/config/backup

Headers:

Cookie: session=your-session-id

Permissions Required: Admin

Response

Success (200):

{
	"success": true,
	"message": "Configuration backup created",
	"backup": {
		"file": ".env.backup.2025-10-05_14-30-00",
		"size": 2048,
		"timestamp": "2025-10-05T14:30:00Z"
	}
}

4. Test Database (Alternative)

Alternative endpoint for testing database connection.

Request

POST /api/config/test-db

Headers:

Content-Type: application/json

Body:

{
	"DB_TYPE": "mongodb",
	"DB_HOST": "mongodb+srv://cluster.mongodb.net",
	"DB_USER": "admin",
	"DB_PASSWORD": "password",
	"DB_NAME": "sveltycms"
}

Permissions Required: Setup mode or admin

Response

Same as /api/setup/test-database

Supports:

  • MongoDB local connections
  • MongoDB Atlas (SRV)
  • MariaDB/MySQL connections
  • Connection string format detection

Cache Management

Clear Cache

Clears all system cache entries.

Request

POST /api/cache/clear

Headers:

Cookie: session=your-session-id

Permissions Required: Admin

Response

Success (200):

{
	"success": true,
	"message": "All cache entries cleared successfully",
	"cleared": 342,
	"timestamp": "2025-10-05T14:30:00Z"
}

Cache Types Cleared:

  • Settings cache
  • Collection cache
  • Media cache
  • User session cache
  • Query result cache

Theme Management

1. Get Current Theme

Retrieves the active theme.

Request

GET /api/theme/get-current-theme

Query Parameters:

  • tenantId (string, optional) - Tenant ID (multi-tenant mode)

Headers:

Cookie: session=your-session-id

Permissions Required: Authenticated user

Response

Success (200):

{
	"success": true,
	"theme": {
		"_id": "theme123",
		"name": "default",
		"displayName": "Default Theme",
		"colors": {
			"primary": "#3498db",
			"secondary": "#2ecc71",
			"accent": "#e74c3c"
		},
		"fonts": {
			"heading": "Inter",
			"body": "Roboto"
		},
		"isDefault": true,
		"tenantId": "default-tenant"
	}
}

2. Update Theme

Changes the active theme.

Request

POST /api/theme/update-theme

Headers:

Cookie: session=your-session-id
Content-Type: application/json

Body:

{
	"themeName": "dark-theme"
}

Permissions Required: Admin or theme:update

Response

Success (200):

{
	"success": true,
	"theme": {
		"_id": "theme456",
		"name": "dark-theme",
		"displayName": "Dark Theme",
		"colors": {
			"primary": "#2c3e50",
			"secondary": "#34495e",
			"accent": "#e74c3c"
		},
		"isDefault": false
	},
	"message": "Theme updated successfully"
}

Error Responses:

// 404 Not Found
{
  "success": false,
  "error": "Theme 'dark-theme' does not exist."
}

// 400 Bad Request
{
  "success": false,
  "error": "Invalid theme name."
}

Database-Agnostic Implementation

Configuration endpoints use abstraction layers:

// Database connection testing uses drivers directly
// but no persistent storage of connection info

// Settings use adapter interface
await dbAdapter.settings.updateSettings(settingsData);
await dbAdapter.setDefaultTheme(themeName, tenantId);

// Theme management through ThemeManager
const themeManager = ThemeManager.getInstance();
await themeManager.setTheme(theme, tenantId);

Multi-Tenancy Support

When multi-tenant mode is enabled:

  • Each tenant can have different themes
  • Configuration scoped per tenant
  • Settings isolated by tenant

Tenant-Scoped Theme:

const query = { name: themeName };
if (MULTI_TENANT) {
	query.tenantId = tenantId;
}
const theme = await dbAdapter.findOne('themes', query);

Setup Wizard Flow

Typical setup flow:

  1. Test Database - Verify connection settings
  2. Install Driver - Auto-install missing drivers (if needed)
  3. Save Configuration - Persist settings to .env
  4. Seed Settings - Initialize database with defaults
  5. Create Admin - Create first admin user
  6. Complete Setup - Mark setup as done

Security Considerations

Setup Mode

  • Setup endpoints accessible without authentication during initial setup
  • Setup mode automatically disabled after completion
  • Cannot re-enable setup mode without database reset

Configuration Security

  • Sensitive values encrypted in storage
  • Configuration files have strict permissions (600)
  • Backups created before changes
  • Admin-only access to configuration

Database Credentials

  • Never logged or returned in responses
  • Encrypted in transit and at rest
  • Masked in configuration display

Testing

JavaScript Example

// Test database connection
const testResponse = await fetch('/api/setup/test-database', {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({
		DB_TYPE: 'mongodb',
		DB_HOST: 'localhost',
		DB_PORT: 27017,
		DB_USER: 'admin',
		DB_PASSWORD: 'password',
		DB_NAME: 'sveltycms'
	})
});

const { success, message } = await testResponse.json();
if (success) {
	console.log('Connection successful!');
}

// Update theme
await fetch('/api/theme/update-theme', {
	method: 'POST',
	credentials: 'include',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify({ themeName: 'dark-theme' })
});

// Clear cache
await fetch('/api/cache/clear', {
	method: 'POST',
	credentials: 'include'
});

Related Documentation

Implementation Details

For implementation details, see:

  • src/routes/api/setup/test-database/+server.ts - Database testing
  • src/routes/api/setup/install-driver/+server.ts - Driver installation
  • src/routes/api/config/save-config/+server.ts - Config persistence
  • src/routes/api/theme/update-theme/+server.ts - Theme management
  • src/routes/api/cache/clear/+server.ts - Cache clearing
  • src/databases/themeManager.ts - Theme manager
  • src/databases/CacheService.ts - Cache service