Settings

FORGE provides a database-backed application settings system with support for typed values, grouping, encryption for sensitive data, and a public/private visibility model. Settings are managed through the admin panel and consumed by both backend and frontend.

Overview

Rather than relying solely on environment variables or configuration files, FORGE stores application settings in the database. This enables administrators to modify application behavior at runtime through the admin interface without redeployment.

Database Schema

The settings table stores all configuration values:

Column	Type	Description
id	UUID	Primary key
group_name	VARCHAR(100)	Setting category (e.g., general, auth, email)
key	VARCHAR(100)	Setting identifier (unique within group)
value	TEXT	Stored value (may be encrypted)
type	VARCHAR(20)	Value type: string, boolean, number, json, encrypted
is_public	BOOLEAN	Whether the setting is exposed to the public API
is_sensitive	BOOLEAN	Whether the value should be masked in the admin UI
created_at	TIMESTAMP	Record creation timestamp
updated_at	TIMESTAMP	Last update timestamp

Setting Groups

Settings are organized into logical groups:

General

Key	Type	Default	Public	Description
app_name	string	"FORGE App"	Yes	Application display name
app_url	string	--	Yes	Base URL of the application
timezone	string	"UTC"	Yes	Default timezone
date_format	string	"YYYY-MM-DD"	Yes	Date display format

Auth

Key	Type	Default	Public	Description
allow_registration	boolean	true	Yes	Whether new users can register
session_lifetime	number	1440	No	Session duration in minutes
password_min_length	number	8	Yes	Minimum password length
require_email_verify	boolean	true	No	Require email verification

Email

Key	Type	Default	Public	Sensitive	Description
email_driver	string	"smtp"	No	No	Email provider
email_host	string	--	No	No	SMTP host address
email_port	number	587	No	No	SMTP port
email_username	string	--	No	No	SMTP username
email_password	encrypted	--	No	Yes	SMTP password
email_encryption	string	"tls"	No	No	Encryption method
email_from_name	string	--	No	No	Sender display name
email_from_address	string	--	No	No	Sender email address

Storage

Key	Type	Default	Public	Description
storage_driver	string	"local"	No	Storage backend
max_upload_size	number	10	Yes	Max file upload size in MB
allowed_types	json	--	Yes	Allowed MIME types for upload

Encryption

Settings with type = "encrypted" are encrypted at rest using AES-256-GCM. The encryption key is provided via the FORGE_ENCRYPTION_KEY environment variable.

┌─────────────────────────────────────────────────────┐
│                 Encryption Flow                      │
├─────────────────────────────────────────────────────┤
│                                                      │
│  Plain Value ──► AES-256-GCM Encrypt ──► Stored     │
│                       │                              │
│              FORGE_ENCRYPTION_KEY                     │
│              (from environment)                       │
│                                                      │
│  Stored Value ──► AES-256-GCM Decrypt ──► Plain     │
│                       │                              │
│              FORGE_ENCRYPTION_KEY                     │
│                                                      │
└─────────────────────────────────────────────────────┘

WARNING

The FORGE_ENCRYPTION_KEY must be set in your environment before the application starts. If the key is lost, all encrypted settings become unrecoverable. Back up this key securely and never commit it to version control.

TIP

Only settings that contain credentials or secrets should use the encrypted type. Common examples include SMTP passwords, API secret keys, and payment provider tokens.

Admin Interface

The admin settings page organizes settings by group with appropriate input controls:

• String -- Text input field
• Boolean -- Toggle switch
• Number -- Numeric input with validation
• JSON -- Code editor with syntax highlighting
• Encrypted -- Password input field (value is masked after saving)

Sensitive settings (where is_sensitive = true) display their values as masked dots in the admin UI. The actual value is only revealed when the administrator explicitly clicks to show it.

WARNING

Encrypted settings display as •••••••• in the admin panel. When editing, the field appears empty. Submitting an empty value for an encrypted field preserves the existing value -- it does not clear it.

Public API

The public settings endpoint returns only settings where is_public = true:

GET /api/settings

Example Response

{
  "general": {
    "app_name": "My Application",
    "app_url": "https://example.com",
    "timezone": "UTC"
  },
  "auth": {
    "allow_registration": true,
    "password_min_length": 8
  },
  "storage": {
    "max_upload_size": 10,
    "allowed_types": ["image/jpeg", "image/png", "application/pdf"]
  }
}

TIP

Private settings (database credentials, API keys, internal configuration) are never exposed through the public API, regardless of the requesting user's role.

Backend Usage

// Get a typed setting value
let app_name: String = settings_service.get("general", "app_name").await?;
let session_lifetime: i64 = settings_service.get("auth", "session_lifetime").await?;
let allow_reg: bool = settings_service.get("auth", "allow_registration").await?;

// Get an encrypted setting (automatically decrypted)
let smtp_password: String = settings_service.get("email", "email_password").await?;

// Update a setting
settings_service.set("general", "app_name", "New App Name").await?;