Global Settings Management - DeployStack - Enterprise Control Plane for MCP

This document describes the global key-value store system with group-based organization for managing application-wide configuration and credentials in DeployStack.

Overview

The global settings system provides secure storage for application-wide configuration values organized into logical groups for better management and frontend display:

SMTP Mail Settings: Host, port, username, password for email functionality
GitHub OAuth Configuration: GitHub OAuth client ID and secret for authentication
API Keys: External service credentials (OpenAI, AWS, etc.)
System Configuration: Application-wide settings and feature flags
Integration Credentials: Third-party service authentication tokens
Environment Variables: Dynamic configuration that can be changed without code deployment

Group-Based Organization

The system now uses groups to organize settings into logical categories that can be displayed as tabs in the frontend:

Group ID: Technical identifier used for API queries (e.g., smtp)
Group Name: Human-readable display name (e.g., SMTP Mail Settings)
Group Metadata: Description, icon, and sort order for frontend display

Auto-Initialization System

The system includes an auto-initialization feature that automatically creates missing groups and global settings when the server starts. Settings are defined in modular files within the src/global-settings/ directory, and the system will:

Scan for setting definition files on startup
Create missing groups with metadata
Check which settings exist in the database
Create missing settings with default values (non-destructive)
Link settings to their appropriate groups
Preserve existing settings and their values
Log initialization results for transparency

Key Features

Group-Based Organization: Settings organized into logical groups for frontend tabs
Hierarchical Keys: Dot notation organization (e.g., smtp.host, api.openai.key)
Encryption Support: Automatic encryption for sensitive values using AES-256-GCM
Group Metadata: Display names, descriptions, icons, and sort order for groups
Admin-Only Access: Only global_admin users can manage settings
Audit Trail: Track setting changes with timestamps
Search Functionality: Find settings by key patterns
Bulk Operations: Create/update multiple settings at once
Health Monitoring: Built-in encryption system health checks

Security

Encryption

Sensitive values are encrypted using industry-standard AES-256-GCM encryption:

Algorithm: AES-256-GCM (Galois/Counter Mode)
Key Derivation: Scrypt with fixed salt from DEPLOYSTACK_ENCRYPTION_SECRET environment variable
Authenticated Encryption: Prevents tampering with encrypted data
Unique IVs: Each encryption operation uses a unique initialization vector
Additional Authenticated Data: Extra security layer to prevent manipulation

Access Control

Role-Based Access: Only users with global_admin role can access settings
Permission-Based: Granular permissions for view, edit, and delete operations
Session Validation: All requests require valid authentication

Environment Variables

The system requires the DEPLOYSTACK_ENCRYPTION_SECRET environment variable:

DEPLOYSTACK_ENCRYPTION_SECRET=your-very-secure-32-character-secret-key-here

Important: Use a strong, unique secret in production. This key is used to derive the encryption key for all sensitive settings.

Security Guidelines

Follow these guidelines when working with sensitive settings:

Always encrypt sensitive data: Passwords, API keys, tokens, and secrets must be encrypted
Use descriptive descriptions: Help administrators understand what each setting does and why it’s sensitive
Group sensitive settings: Keep all sensitive settings for a service in the same group for easier management
Regular audits: Review settings periodically for unused or outdated values
Environment separation: Use different encryption secrets for different environments (development, staging, production)

Database Schema

-- Groups table for organizing settings
CREATE TABLE globalSettingGroups (
  id TEXT PRIMARY KEY,                     -- Group identifier (e.g., 'smtp')
  name TEXT NOT NULL,                      -- Display name (e.g., 'SMTP Mail Settings')
  description TEXT,                        -- Group description
  icon TEXT,                               -- Optional icon (lucide) for frontend 
  sort_order INTEGER DEFAULT 0 NOT NULL,  -- Display order for tabs
  created_at INTEGER NOT NULL,             -- Creation timestamp
  updated_at INTEGER NOT NULL              -- Last update timestamp
);

-- Settings table with group reference
CREATE TABLE globalSettings (
  key TEXT PRIMARY KEY,                    -- Setting identifier (e.g., 'smtp.host')
  value TEXT NOT NULL,                     -- Setting value (encrypted if sensitive)
  description TEXT,                        -- Human-readable description
  is_encrypted BOOLEAN NOT NULL DEFAULT FALSE, -- Whether value is encrypted
  group_id TEXT REFERENCES globalSettingGroups(id), -- Group reference
  created_at INTEGER NOT NULL,             -- Creation timestamp
  updated_at INTEGER NOT NULL              -- Last update timestamp
);

Naming Conventions

When creating global settings, follow these conventions for consistency:

Dot notation for hierarchy: Use category.subcategory.setting structure (e.g., smtp.host, api.openai.key)
Lowercase with underscores: Use lowercase letters with underscores for readability (e.g., smtp.max_retry_count)
Be descriptive but concise: Use clear names without redundancy (e.g., api.openai.key not api.openai.api_key)
Group related settings: Keep related configuration together (e.g., database.host, database.port, database.name)
Hierarchical keys within groups: Use dot notation for subcategories (e.g., group.subcategory.setting)
Keep all related settings in the same group: Maintain group consistency for better organization
Provide clear descriptions: Help administrators understand the purpose of each setting

API Endpoints

Authentication

All endpoints require authentication and appropriate permissions:

View Settings: Requires settings.view permission
Create/Update Settings: Requires settings.edit permission
Delete Settings: Requires settings.delete permission

Group Management

Get All Groups with Settings

GET /api/settings/groups
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": [
    {
      "id": "smtp",
      "name": "SMTP Mail Settings",
      "description": "Email server configuration for sending notifications",
      "icon": "mail",
      "sort_order": 1,
      "settings": [
        {
          "key": "smtp.host",
          "value": "smtp.gmail.com",
          "description": "SMTP server hostname",
          "is_encrypted": false,
          "created_at": "2025-01-06T20:00:00.000Z",
          "updated_at": "2025-01-06T20:00:00.000Z"
        }
      ],
      "created_at": "2025-01-06T20:00:00.000Z",
      "updated_at": "2025-01-06T20:00:00.000Z"
    }
  ]
}

Get Specific Group

GET /api/settings/groups/:groupId
Authorization: Bearer <token>

Create Group

POST /api/settings/groups
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "api-keys",
  "name": "API Keys",
  "description": "External service API keys and credentials",
  "icon": "key",
  "sort_order": 3
}

Update Group

PUT /api/settings/groups/:groupId
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Group Name",
  "description": "Updated description",
  "sort_order": 2
}

Settings Management

List All Settings

GET /api/settings
Authorization: Bearer <token>

Get Settings by Group

GET /api/settings/group/:groupId
Authorization: Bearer <token>

Example:

GET /api/settings/group/smtp

Get Specific Setting

GET /api/settings/:key
Authorization: Bearer <token>

Create New Setting

POST /api/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "smtp.password",
  "value": "secret123",
  "description": "SMTP server password",
  "encrypted": true,
  "group_id": "smtp"
}

Update Existing Setting

PUT /api/settings/:key
Authorization: Bearer <token>
Content-Type: application/json

{
  "value": "new-secret-value",
  "description": "Updated SMTP password",
  "encrypted": true,
  "group_id": "smtp"
}

Delete Setting

DELETE /api/settings/:key
Authorization: Bearer <token>

Search Settings

POST /api/settings/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "pattern": "smtp"
}

Bulk Create/Update Settings

POST /api/settings/bulk
Authorization: Bearer <token>
Content-Type: application/json

{
  "settings": [
    {
      "key": "smtp.host",
      "value": "smtp.gmail.com",
      "group_id": "smtp"
    },
    {
      "key": "smtp.port",
      "value": "587",
      "group_id": "smtp"
    },
    {
      "key": "smtp.password",
      "value": "secret123",
      "encrypted": true,
      "group_id": "smtp"
    }
  ]
}

Health Check

GET /api/settings/health
Authorization: Bearer <token>

Helper Methods (Recommended)

The GlobalSettings helper class provides simple, type-safe methods for retrieving setting values. These helpers are designed for common use cases where you just need the value of a setting, similar to the Email service helper methods.

Import the Helper Class

import { GlobalSettings } from '../global-settings';
// or
import { GlobalSettings } from '../global-settings/helpers';

Basic Usage

Get Setting Values

// Get a string value
const smtpHost = await GlobalSettings.get('smtp.host');
const smtpHostWithDefault = await GlobalSettings.get('smtp.host', 'localhost');

// Get typed values
const maxRetries = await GlobalSettings.getNumber('system.max_retries', 3);
const debugMode = await GlobalSettings.getBoolean('system.debug', false);
const apiUrl = await GlobalSettings.getUrl('api.base_url');
const supportEmail = await GlobalSettings.getEmail('support.email');

// Get required values (throws if missing)
const databaseUrl = await GlobalSettings.getRequired('database.url');

Type-Safe Getters

// Boolean values (accepts: 'true', 'false', '1', '0', 'yes', 'no', 'on', 'off', 'enabled', 'disabled')
const maintenanceMode = await GlobalSettings.getBoolean('system.maintenance_mode', false);
const emailEnabled = await GlobalSettings.getBoolean('email.enabled', true);

// Numeric values
const uploadLimit = await GlobalSettings.getNumber('upload.max_size_mb', 10);
const retryCount = await GlobalSettings.getInteger('api.retry_count', 3);

// URL validation
const webhookUrl = await GlobalSettings.getUrl('webhook.endpoint');
const callbackUrl = await GlobalSettings.getUrl('oauth.callback', 'http://localhost:3000/callback');

// Email validation
const adminEmail = await GlobalSettings.getEmail('admin.email');
const fromEmail = await GlobalSettings.getEmail('smtp.from_email', 'noreply@example.com');

Advanced Data Types

// JSON objects
interface ApiConfig {
  timeout: number;
  retries: number;
  endpoints: string[];
}
const apiConfig = await GlobalSettings.getJson<ApiConfig>('api.config');

// Arrays (comma-separated values)
const allowedDomains = await GlobalSettings.getArray('security.allowed_domains');
const adminEmails = await GlobalSettings.getArray('admin.emails', ['admin@example.com']);

Batch Operations

Get Multiple Settings

// Get multiple settings at once
const settings = await GlobalSettings.getMultiple([
  'smtp.host',
  'smtp.port', 
  'smtp.username'
]);
// Returns: { 'smtp.host': 'smtp.gmail.com', 'smtp.port': '587', 'smtp.username': 'user@gmail.com' }

// Get all settings in a group (without group prefix)
const smtpConfig = await GlobalSettings.getGroupValues('smtp');
// Returns: { 'host': 'smtp.gmail.com', 'port': '587', 'username': 'user@gmail.com', ... }

// Get all settings in a group (with full keys)
const smtpSettings = await GlobalSettings.getGroupValuesWithFullKeys('smtp');
// Returns: { 'smtp.host': 'smtp.gmail.com', 'smtp.port': '587', 'smtp.username': 'user@gmail.com', ... }

Utility Methods

Check Setting Status

// Check if setting exists and has a value
if (await GlobalSettings.isSet('smtp.host')) {
  logger.info('SMTP host is configured');
}

// Check if setting is empty
if (await GlobalSettings.isEmpty('api.key')) {
  logger.warn('API key needs to be configured');
}

// Check if setting exists in database (regardless of value)
if (await GlobalSettings.exists('feature.new_ui')) {
  logger.info('New UI feature flag exists');
}

Error Handling

try {
  // This will throw if the setting is missing or empty
  const requiredApiKey = await GlobalSettings.getRequired('api.secret_key');
  
  // Use the API key
  const response = await fetch('/api/data', {
    headers: { 'Authorization': `Bearer ${requiredApiKey}` }
  });
} catch (error) {
  logger.error('Required setting missing:', error.message);
  // Handle missing configuration
}

Real-World Examples

SMTP Configuration

import { GlobalSettings } from '../global-settings';

// Simple approach using helpers
const smtpConfig = {
  host: await GlobalSettings.getRequired('smtp.host'),
  port: await GlobalSettings.getNumber('smtp.port', 587),
  secure: await GlobalSettings.getBoolean('smtp.secure', true),
  auth: {
    user: await GlobalSettings.getRequired('smtp.username'),
    pass: await GlobalSettings.getRequired('smtp.password'),
  },
  from: {
    name: await GlobalSettings.get('smtp.from_name', 'DeployStack'),
    address: await GlobalSettings.get('smtp.from_email') || await GlobalSettings.getRequired('smtp.username'),
  }
};

// Or get all SMTP settings at once
const smtpSettings = await GlobalSettings.getGroupValues('smtp');
const smtpConfigFromGroup = {
  host: smtpSettings.host,
  port: parseInt(smtpSettings.port || '587'),
  secure: smtpSettings.secure === 'true',
  auth: {
    user: smtpSettings.username,
    pass: smtpSettings.password,
  }
};

Feature Flags

// Check feature flags
const features = {
  newDashboard: await GlobalSettings.getBoolean('features.new_dashboard', false),
  apiV2: await GlobalSettings.getBoolean('features.api_v2', false),
  debugMode: await GlobalSettings.getBoolean('system.debug', false),
  maintenanceMode: await GlobalSettings.getBoolean('system.maintenance', false),
};

if (features.maintenanceMode) {
  return res.status(503).json({ error: 'System under maintenance' });
}

API Configuration

// API service configuration
const apiConfig = {
  baseUrl: await GlobalSettings.getUrl('api.base_url', 'https://api.example.com'),
  timeout: await GlobalSettings.getNumber('api.timeout_ms', 30000),
  retries: await GlobalSettings.getInteger('api.max_retries', 3),
  apiKey: await GlobalSettings.getRequired('api.secret_key'),
  allowedOrigins: await GlobalSettings.getArray('api.allowed_origins', ['localhost']),
};

// Use in API client
const response = await fetch(`${apiConfig.baseUrl}/data`, {
  timeout: apiConfig.timeout,
  headers: {
    'Authorization': `Bearer ${apiConfig.apiKey}`,
    'Content-Type': 'application/json'
  }
});

System Configuration

// System-wide settings
const systemConfig = {
  maxUploadSize: await GlobalSettings.getNumber('system.max_upload_mb', 10),
  sessionTimeout: await GlobalSettings.getNumber('system.session_timeout_hours', 24),
  logLevel: await GlobalSettings.get('system.log_level', 'info'),
  adminEmails: await GlobalSettings.getArray('system.admin_emails'),
  supportEmail: await GlobalSettings.getEmail('system.support_email', 'support@example.com'),
};

Usage Examples (GlobalSettingsService)

For more complex operations like creating, updating, or searching settings, use the GlobalSettingsService directly:

SMTP Configuration

import { GlobalSettingsService } from '../services/globalSettingsService';

// Set SMTP configuration
await GlobalSettingsService.set('smtp.host', 'smtp.gmail.com', { 
  group_id: 'smtp',
  description: 'SMTP server hostname'
});

await GlobalSettingsService.set('smtp.port', '587', { 
  group_id: 'smtp',
  description: 'SMTP server port'
});

await GlobalSettingsService.set('smtp.username', 'user@gmail.com', { 
  group_id: 'smtp',
  description: 'SMTP authentication username'
});

await GlobalSettingsService.set('smtp.password', 'app-password', { 
  group_id: 'smtp',
  description: 'SMTP authentication password',
  encrypted: true
});

// Retrieve SMTP configuration by group
const smtpSettings = await GlobalSettingsService.getByGroup('smtp');
const smtpConfig = {
  host: smtpSettings.find(s => s.key === 'smtp.host')?.value,
  port: parseInt(smtpSettings.find(s => s.key === 'smtp.port')?.value || '587'),
  auth: {
    user: smtpSettings.find(s => s.key === 'smtp.username')?.value,
    pass: smtpSettings.find(s => s.key === 'smtp.password')?.value,
  }
};

API Keys Management

// Store encrypted API keys
await GlobalSettingsService.set('api.openai.key', 'sk-...', { 
  group_id: 'api-keys',
  description: 'OpenAI API key for AI integrations',
  encrypted: true
});

await GlobalSettingsService.set('api.aws.access_key', 'AKIA...', { 
  group_id: 'api-keys',
  description: 'AWS access key for cloud services',
  encrypted: true
});

// Retrieve API configuration by group
const apiSettings = await GlobalSettingsService.getByGroup('api-keys');
const openaiKey = apiSettings.find(s => s.key === 'api.openai.key')?.value;

Error Handling

When working with global settings, implement proper error handling:

try {
  const setting = await GlobalSettingsService.get('api.openai.key');
  if (!setting) {
    throw new Error('OpenAI API key not configured');
  }
  // Use the setting
} catch (error) {
  logger.error('Failed to retrieve setting:', error);
  // Handle the error appropriately
}

Auto-Initialization System

Overview

The auto-initialization system automatically creates missing groups and global settings when the server starts. This ensures that all required groups and settings are available without manual configuration, while preserving existing values.

File-Based Setting Definitions

Settings are defined in TypeScript files within the src/global-settings/ directory:

src/global-settings/
├── types.ts              # Type definitions
├── index.ts              # Auto-discovery service
├── smtp.ts               # SMTP configuration
├── github-oauth.ts       # GitHub OAuth settings
└── [custom].ts           # Your custom settings

Setting Definition Format

Each setting file exports a GlobalSettingsModule with group metadata:

// src/global-settings/smtp.ts
import type { GlobalSettingsModule } from './types';

export const smtpSettings: GlobalSettingsModule = {
  group: {
    id: 'smtp',
    name: 'SMTP Mail Settings',
    description: 'Email server configuration for sending notifications',
    icon: 'mail',
    sort_order: 1
  },
  settings: [
    {
      key: 'smtp.host',
      name: 'SMTP Host',
      defaultValue: '',
      type: 'string',
      description: 'SMTP server hostname (e.g., smtp.gmail.com)',
      encrypted: false,
      required: true
    },
    {
      key: 'smtp.password',
      name: 'SMTP Password',
      defaultValue: '',
      type: 'string',
      description: 'SMTP authentication password',
      encrypted: true,
      required: true
    }
    // ... more settings
  ]
};

Setting Properties

Each setting in the settings array requires these properties:

Property	Type	Required	Description
`key`	`string`	Yes	Unique identifier using dot notation (e.g., `smtp.host`)
`name`	`string`	Yes	Human-readable label for frontend display (e.g., `SMTP Host`)
`defaultValue`	`string \| number \| boolean`	Yes	Default value when setting is created
`type`	`'string' \| 'number' \| 'boolean'`	Yes	Value type for validation and UI rendering
`description`	`string`	Yes	Help text explaining what the setting does
`encrypted`	`boolean`	Yes	Whether to encrypt the value in the database
`required`	`boolean`	Yes	Whether the setting must have a non-empty value

Startup Behavior

When the server starts:

Discovery: Scans src/global-settings/ for .ts files
Loading: Dynamically imports each settings module
Validation: Ensures each module has the correct structure
Group Creation: Creates missing groups with metadata
Database Check: Checks which settings exist in the database
Creation: Creates missing settings with default values and group links
Preservation: Skips existing settings (non-destructive)
Logging: Reports initialization results

Example Startup Output

🔄 Loading global settings definitions...
📁 Found 2 setting files: smtp, github-oauth
✅ Loaded settings module: smtp (7 settings)
✅ Loaded settings module: github-oauth (5 settings)
🎉 Loaded 2 settings modules with 12 total settings
🔄 Creating 2 setting groups...
✅ Created group: smtp (SMTP Mail Settings)
✅ Created group: github-oauth (GitHub OAuth Configuration)
🔄 Initializing 12 global settings...
✅ Created setting: smtp.host
✅ Created setting: smtp.port
✅ Created setting: smtp.username
✅ Created setting: smtp.password
⏭️  Skipped existing setting: smtp.secure
✅ Created setting: github.oauth.client_id
✅ Created setting: github.oauth.client_secret
🎉 Global settings initialization complete: 6 created, 1 skipped
⚠️  Missing required settings: smtp.host, smtp.username, smtp.password

Built-in Setting Groups

SMTP Settings (Group ID: `smtp`)

Source: services/backend/src/global-settings/smtp.ts Email server configuration for sending notifications and system emails. Includes SMTP host, port, authentication credentials (encrypted password), SSL/TLS settings, and default sender information.

GitHub OAuth Settings (Group ID: `github-oauth`)

Source: services/backend/src/global-settings/github-oauth.ts GitHub OAuth application credentials for user authentication. Includes client ID, client secret (encrypted), enabled flag, callback URL, and requested OAuth scopes.

Global Settings (Group ID: `global`)

Source: services/backend/src/global-settings/global.ts Application-wide configuration settings. Controls frontend URL, email functionality toggle, login/registration enablement, and API documentation visibility.

User Display Settings (Group ID: `user-display`)

Source: services/backend/src/global-settings/user-display.ts Controls UI element visibility for users across the application. Manages header buttons like Discord community link and feedback form. Special behavior: These settings are automatically included in the /api/users/me endpoint response, making them immediately available to the frontend without additional API calls.

Helper Methods

The system provides helper methods for retrieving complete configurations:

import { GlobalSettingsInitService } from '../global-settings';

// Get complete SMTP configuration
const smtpConfig = await GlobalSettingsInitService.getSmtpConfiguration();
if (smtpConfig) {
  // Use smtpConfig.host, smtpConfig.port, etc.
}

// Get complete GitHub OAuth configuration
const githubConfig = await GlobalSettingsInitService.getGitHubOAuthConfiguration();
if (githubConfig && githubConfig.enabled) {
  // Use githubConfig.clientId, githubConfig.clientSecret, etc.
}

// Check if services are configured
const isSmtpReady = await GlobalSettingsInitService.isSmtpConfigured();
const isGitHubReady = await GlobalSettingsInitService.isGitHubOAuthConfigured();

Adding New Setting Groups (Core)

To add a new core setting group (managed directly by the application):

Create Setting File: Add a new .ts file in src/global-settings/

// src/global-settings/my-service.ts
import type { GlobalSettingsModule } from './types';

export const myServiceSettings: GlobalSettingsModule = {
  group: {
    id: 'my-service',
    name: 'My Service Configuration',
    description: 'Settings for My Service integration',
    icon: 'service',
    sort_order: 3
  },
  settings: [
    {
      key: 'my-service.api_key',
      name: 'API Key',
      defaultValue: '',
      type: 'string',
      description: 'API key for My Service',
      encrypted: true,
      required: true
    },
    {
      key: 'my-service.enabled',
      name: 'Enable Service',
      defaultValue: false,
      type: 'boolean',
      description: 'Enable My Service integration',
      encrypted: false,
      required: false
    }
  ]
};

Restart Server: The new group and settings will be automatically discovered and initialized
Add Helper Method (optional): Add a helper method to GlobalSettingsInitService

// In src/global-settings/index.ts
static async getMyServiceConfiguration(): Promise<MyServiceConfig | null> {
  const settings = await GlobalSettingsService.getByGroup('my-service');
  
  const apiKey = settings.find(s => s.key === 'my-service.api_key')?.value;
  const enabled = settings.find(s => s.key === 'my-service.enabled')?.value;
  
  if (enabled !== 'true' || !apiKey) {
    return null;
  }
  
  return {
    apiKey,
    enabled: enabled === 'true'
  };
}

Frontend Integration

The group-based system is designed for easy frontend integration:

Dynamic Tab Creation

// Frontend can easily create tabs from groups
const response = await fetch('/api/settings/groups');
const { data: groups } = await response.json();

groups.forEach(group => {
  createTab({
    id: group.id,           // For routing: /settings/smtp
    label: group.name,      // Display: "SMTP Mail Settings"
    icon: group.icon,       // UI icon
    description: group.description,
    settings: group.settings, // Tab content
    sortOrder: group.sort_order
  });
});

Group Management

// Get settings for a specific tab/group
const smtpSettings = await fetch('/api/settings/group/smtp');

// Update a setting within a group
await fetch('/api/settings/smtp.host', {
  method: 'PUT',
  body: JSON.stringify({
    value: 'new-smtp-host.com',
    group_id: 'smtp'
  })
});

System Configuration

// System-wide feature flags and configuration
await GlobalSettingsService.set('system.maintenance_mode', 'false', { 
  group_id: 'system',
  description: 'Enable/disable maintenance mode'
});

await GlobalSettingsService.set('system.max_upload_size', '10485760', { 
  group_id: 'system',
  description: 'Maximum file upload size in bytes (10MB)'
});

await GlobalSettingsService.set('system.debug_logging', 'false', { 
  group_id: 'system',
  description: 'Enable debug logging'
});

// Check system configuration
const maintenanceMode = (await GlobalSettingsService.get('system.maintenance_mode'))?.value === 'true';
const maxUploadSize = parseInt((await GlobalSettingsService.get('system.max_upload_size'))?.value || '5242880');

Group Design Guidelines

When designing setting groups for your application, follow these guidelines:

Logical grouping: Group related settings together (e.g., all SMTP settings in one group)
Clear names: Use descriptive group names that are clear for frontend display
Consistent icons: Use consistent iconography across groups for better UX
Proper ordering: Set sort_order values to control tab display sequence in the frontend

Performance Considerations

In-Memory Cache

The global settings system uses an in-memory cache to eliminate database queries for read operations. This is critical for high-frequency endpoints like health checks (/) and Swagger documentation (/documentation).

How It Works

┌─────────────────────────────────────────────────────────────┐
│                      Architecture                           │
├─────────────────────────────────────────────────────────────┤
│  Server Start → GlobalSettingsCache.load() → Memory Cache   │
│                                                             │
│  READ:  GlobalSettings.get() → Memory (instant, no DB)      │
│                                                             │
│  WRITE: GlobalSettingsService.set/update/delete()           │
│           → DB + Cache Invalidation (reload from DB)        │
└─────────────────────────────────────────────────────────────┘

Cache Lifecycle

Startup: After global settings initialization, all settings are loaded into memory
Reads: All GlobalSettings.get*() calls read from memory (no database query)
Writes: When settings are modified via GlobalSettingsService, the cache is automatically invalidated and reloaded
Fallback: If cache is not initialized, reads fall back to database queries

When Cache Is Invalidated

The cache automatically reloads from the database after:

GlobalSettingsService.set() - Create or update a setting
GlobalSettingsService.setTyped() - Create or update with type
GlobalSettingsService.update() - Update an existing setting
GlobalSettingsService.delete() - Delete a setting

Manual Cache Refresh

If you modify settings outside of GlobalSettingsService (not recommended), refresh the cache manually:

import { GlobalSettings } from '../global-settings';

await GlobalSettings.refreshCaches();

Single-Instance Limitation

The current cache implementation is designed for single-instance deployments. Multi-instance support (horizontal scaling) with shared cache synchronization is planned for a future release.

Monitoring Cache Status

import { GlobalSettingsCache } from '../global-settings';

// Check if cache is ready
if (GlobalSettingsCache.isInitialized()) {
  console.log(`Cache has ${GlobalSettingsCache.size()} settings`);
}

Additional Performance Tips

Batch operations: Use bulk endpoints when creating multiple related settings
Group retrieval: Use getGroupValues() to fetch all settings in a group at once

Migration and Setup

Initial Setup

Environment Variable: Set DEPLOYSTACK_ENCRYPTION_SECRET in your environment
Database Migration: Run npm run db:generate and restart the server
Admin Access: Ensure you have a user with global_admin role

Migrating from Category-Based System

The new group-based system replaces the old category-based approach. The migration is handled automatically:

Database Migration: The category column is renamed to group_id
Auto-Initialization: Groups are created automatically from setting definitions
Setting Linking: Existing settings are linked to appropriate groups

Plugin-Contributed Global Settings

In addition to core global settings, plugins can also define and register their own global settings and setting groups. These are managed through the same system and are subject to the same access controls (i.e., editable by global_admin). Key points for plugin-contributed settings:

Declaration: Plugins declare global settings via a globalSettingsExtension property in their main class.
Initialization: The PluginManager processes these definitions at startup, creating new groups and settings if they don’t already exist.
Precedence: Core global settings always take precedence. If a plugin tries to define a setting with a key that already exists (either from core or another plugin), the plugin’s definition for that specific key is ignored.
Documentation: For details on how plugins can define global settings, refer to the Backend Plugins Docs document.

Helper Methods API Reference

GlobalSettings Class Methods

Method	Description	Returns
`get(key, defaultValue?)`	Get a setting value as string	`Promise<string \| null>`
`getString(key, defaultValue?)`	Get a setting value as string (alias)	`Promise<string \| null>`
`getBoolean(key, defaultValue?)`	Get a setting value as boolean	`Promise<boolean \| null>`
`getNumber(key, defaultValue?)`	Get a setting value as number	`Promise<number \| null>`
`getInteger(key, defaultValue?)`	Get a setting value as integer	`Promise<number \| null>`
`getUrl(key, defaultValue?)`	Get and validate setting as URL	`Promise<string \| null>`
`getEmail(key, defaultValue?)`	Get and validate setting as email	`Promise<string \| null>`
`getJson<T>(key, defaultValue?)`	Get and parse setting as JSON	`Promise<T \| null>`
`getArray(key, defaultValue?)`	Get setting as array (comma-separated)	`Promise<string[]>`
`getRequired(key)`	Get required setting (throws if missing)	`Promise<string>`
`getMultiple(keys)`	Get multiple settings at once	`Promise<Record<string, string \| null>>`
`getGroupValues(groupId)`	Get group settings (without prefix)	`Promise<Record<string, string \| null>>`
`getGroupValuesWithFullKeys(groupId)`	Get group settings (with full keys)	`Promise<Record<string, string \| null>>`
`isSet(key)`	Check if setting exists and has value	`Promise<boolean>`
`isEmpty(key)`	Check if setting is empty	`Promise<boolean>`
`exists(key)`	Check if setting exists in database	`Promise<boolean>`
`getRaw(key)`	Get raw setting object with metadata	`Promise<GlobalSetting \| null>`
`refreshCaches()`	Refresh any cached configurations	`Promise<void>`

Boolean Value Parsing

The getBoolean() method accepts these string values:

Value	Result
`'true'`, `'1'`, `'yes'`, `'on'`, `'enabled'`	`true`
`'false'`, `'0'`, `'no'`, `'off'`, `'disabled'`	`false`

Usage Patterns

Simple Value Retrieval

const value = await GlobalSettings.get('key.name');
const valueWithDefault = await GlobalSettings.get('key.name', 'default');

Type-Safe Retrieval

const isEnabled = await GlobalSettings.getBoolean('feature.enabled', false);
const maxSize = await GlobalSettings.getNumber('upload.max_size', 10);
const apiUrl = await GlobalSettings.getUrl('api.endpoint');

Batch Retrieval

const settings = await GlobalSettings.getMultiple(['key1', 'key2', 'key3']);
const groupSettings = await GlobalSettings.getGroupValues('smtp');

Validation and Checks

if (await GlobalSettings.isSet('api.key')) {
  const apiKey = await GlobalSettings.getRequired('api.key');
}

REST API Reference Summary

Endpoint	Method	Permission	Description
`/api/settings/groups`	GET	`settings.view`	List all groups with settings
`/api/settings/groups/:groupId`	GET	`settings.view`	Get specific group
`/api/settings/groups`	POST	`settings.edit`	Create new group
`/api/settings/groups/:groupId`	PUT	`settings.edit`	Update group
`/api/settings`	GET	`settings.view`	List all settings
`/api/settings/:key`	GET	`settings.view`	Get specific setting
`/api/settings`	POST	`settings.edit`	Create new setting
`/api/settings/:key`	PUT	`settings.edit`	Update setting
`/api/settings/:key`	DELETE	`settings.delete`	Delete setting
`/api/settings/group/:groupId`	GET	`settings.view`	Get settings by group
`/api/settings/search`	POST	`settings.view`	Search settings
`/api/settings/bulk`	POST	`settings.edit`	Bulk create/update
`/api/settings/health`	GET	`settings.view`	System health check

For more information about the role-based access control system, see ROLES. For security details, see SECURITY.

Basics

Advanced

API

Database

Auth

Satellite

Documentation Index

​Overview

​Group-Based Organization

​Auto-Initialization System

​Key Features

​Security

​Encryption

​Access Control

​Environment Variables

​Security Guidelines

​Database Schema

​Naming Conventions

​API Endpoints

​Authentication

​Group Management

​Get All Groups with Settings

​Get Specific Group

​Create Group

​Update Group

​Settings Management

​List All Settings

​Get Settings by Group

​Get Specific Setting

​Create New Setting

​Update Existing Setting

​Delete Setting

​Search Settings

​Bulk Create/Update Settings

​Health Check

​Helper Methods (Recommended)

​Import the Helper Class

​Basic Usage

​Get Setting Values

​Type-Safe Getters

​Advanced Data Types

​Batch Operations

​Get Multiple Settings

​Utility Methods

​Check Setting Status

​Error Handling

​Real-World Examples

​SMTP Configuration

​Feature Flags

​API Configuration

​System Configuration

​Usage Examples (GlobalSettingsService)

​SMTP Configuration

​API Keys Management

​Error Handling

​Auto-Initialization System

​Overview

​File-Based Setting Definitions

​Setting Definition Format

​Setting Properties

​Startup Behavior

​Example Startup Output

​Built-in Setting Groups

​SMTP Settings (Group ID: smtp)

​GitHub OAuth Settings (Group ID: github-oauth)

​Global Settings (Group ID: global)

​User Display Settings (Group ID: user-display)

​Helper Methods

​Adding New Setting Groups (Core)

​Frontend Integration

​Dynamic Tab Creation

​Group Management

​System Configuration

​Group Design Guidelines

​Performance Considerations

​In-Memory Cache

​How It Works

​Cache Lifecycle

​When Cache Is Invalidated

​Manual Cache Refresh

Overview

Group-Based Organization

Auto-Initialization System

Key Features

Security

Encryption

Access Control

Environment Variables

Security Guidelines

Database Schema

Naming Conventions

API Endpoints

Authentication

Group Management

Get All Groups with Settings

Get Specific Group

Create Group

Update Group

Settings Management

List All Settings

Get Settings by Group

Get Specific Setting

Create New Setting

Update Existing Setting

Delete Setting

Search Settings

Bulk Create/Update Settings

Health Check

Helper Methods (Recommended)

Import the Helper Class

Basic Usage

Get Setting Values

Type-Safe Getters

Advanced Data Types

Batch Operations

Get Multiple Settings

Utility Methods

Check Setting Status

Error Handling

Real-World Examples

SMTP Configuration

Feature Flags

API Configuration

System Configuration

Usage Examples (GlobalSettingsService)

SMTP Configuration

API Keys Management

Error Handling

Auto-Initialization System

Overview

File-Based Setting Definitions

Setting Definition Format

Setting Properties

Startup Behavior

Example Startup Output

Built-in Setting Groups

SMTP Settings (Group ID: `smtp`)

GitHub OAuth Settings (Group ID: `github-oauth`)

Global Settings (Group ID: `global`)

User Display Settings (Group ID: `user-display`)

Helper Methods

Adding New Setting Groups (Core)

Frontend Integration

Dynamic Tab Creation

Group Management

System Configuration

Group Design Guidelines

Performance Considerations

In-Memory Cache

How It Works

Cache Lifecycle

When Cache Is Invalidated

Manual Cache Refresh

Single-Instance Limitation

Monitoring Cache Status

Additional Performance Tips

Migration and Setup

Initial Setup

Migrating from Category-Based System

Plugin-Contributed Global Settings