Skip to main content

How to Provision Default Settings

In Framework M, you can configure your application to run perfectly "out of the box" without requiring complex database seeding scripts. You do this by providing declarative fallback configurations (TOML files) that the framework reads dynamically when the database is empty.

This guide explains how to set up both Global Settings (Singletons) and Record-Level Defaults.

1. Global Settings (Virtual Singletons)​

For Singleton DocTypes like SystemSettings, the framework automatically looks for a framework_config.toml file in the current working directory if no database record exists.

Step 1: Create the Config File​

Create a framework_config.toml file in the root of your project (where you run m prod or m dev). Add a namespace matching the exact name of your DocType:

# framework_config.toml

[SystemSettings]
app_name = "My Awesome App"
language = "en"
timezone = "UTC"

# You can also configure arrays, like Landing Candidates:
[[SystemSettings.landing_candidates]]
route = "/app/dashboard"

# Configure global logging and security redaction policies:
[logging]
enabled = true
# Note: "password", "token", and "authorization" are always redacted by default
redact_keys = ["stripe_secret", "aws_access_key"]
mask_keys = ["email", "phone"]

When your application boots, calls to singles_manager.get(SystemSettings) will automatically parse this file and return a fully-hydrated "Virtual Singleton" until a system administrator saves a permanent override in the Desk UI.

2. Record-Level Defaults​

For standard, multi-record DocTypes (like Employee or Invoice), you can define fallback values that automatically merge with user input when a new record is created.

Step 1: Declare the Defaults File​

In your DocType's Meta class, use the defaults_file property to point to a specific TOML file.

# src/my_app/doctypes/employee.py
from framework_m import BaseDocType, Field

class Employee(BaseDocType):
    name: str
    department: str
    leave_days: int

    class Meta:
        # Point to a specific configuration file for this DocType
        defaults_file = "my_app/config/hr_defaults.toml"

Step 2: Create the Fallback Configuration​

Create the corresponding TOML file and define the default values:

# src/my_app/config/hr_defaults.toml

[Employee]
department = "General"
leave_days = 20

When a user submits a new Employee record with just {"name": "Alice"}, the framework will automatically inject department="General" and leave_days=20 before saving it to the database.

3. Packaging Your Defaults​

If you are distributing your application as a Python package (.whl), you must ensure your TOML configuration files are included in the build.

If you are using hatchling (the default for uv and Framework M), update your pyproject.toml to force-include the config files:

[tool.hatch.build.targets.wheel.force-include]
"src/my_app/config" = "my_app/config"

4. Deployment Overrides (DevOps)​

Because Framework M reads these TOML files at runtime using standard file paths, overriding them in production is incredibly easy.

In a Kubernetes or Docker environment, simply mount a ConfigMap or volume containing your production framework_config.toml directly into the container's working directory. The framework will instantly read the mounted production settings instead of your default development settings.