Site Config in Frappe Framework (Version 15): Complete Documentation

The site_config.json file is the central configuration file for every site in the Frappe Framework ecosystem. It contains essential site-level settings such as database credentials, encryption keys, rate limits, developer flags, and system configurations.

In Frappe Version 15, site_config.json continues to be the authoritative source for all site-specific configurations and is automatically created whenever a new site is generated using bench new-site.

1. What Is site_config.json in Frappe?

site_config.json is a JSON file located inside each site directory that stores database credentials, encryption keys, and other site-level settings in Frappe v15. It is automatically read by the framework at runtime to determine how the site operates.

2. Where site_config.json Is Located

Every site in Frappe contains its own configuration file:

sites/
└── <site_name>/
├── site_config.json
└── ...

Example:

sites/erp.mysite.com/site_config.json

This file must never be publicly exposed, version-controlled, or shared, as it contains sensitive credentials.

3. Core Keys Found in site_config.json (Frappe v15 Accurate)

Below is a standard auto-generated site config:

{
"db_name": "xxxx",
"db_password": "xxxx",
"db_type": "mariadb",
"encryption_key": "xxxx",
"admin_password": "xxxx"
}

Mandatory Keys

Optional but Common Keys

4. How Frappe Reads site_config.json

Frappe automatically loads the configuration at runtime using:

• Python module: frappe.utils.site_config
• Internal API: frappe.get_site_config()

Example:

config = frappe.get_site_config()
db_name = config.get("db_name")

This ensures that all site-level settings are securely available to the framework.

5. How to Edit site_config.json Safely

You can edit the file manually or with CLI tools.

Recommended Method (Bench Command)

bench set-config key value --site site1.local

• Automatically formats JSON
• Prevents syntax errors
• Reloads cache

Example: Enable Developer Mode

bench set-config developer_mode 1 --site site1.local
bench clear-cache

Manual Editing (Use only when necessary)

sites/site1.local/site_config.json

6. Common site_config.json Settings in Frappe v15

 Developer Mode

"developer_mode": 1

Disable Global Website Cache

"disable_website_cache": 1

Enable Rate Limits

"limits": {
"daily_api_calls": 20000,
"hourly_api_calls": 2000
}

 Maintenance Mode

"maintenance_mode": 1

7. Security Guidelines (Critical for ERPNext Deployments)

• Never upload site_config.json to GitHub
• Restrict server file access
• Rotate DB passwords after migrations
• Secure the encryption_key—used for password & token encryption
• Use strong admin passwords
• Avoid modifying database keys manually

8. Using site_config.json in Multi-Tenant Environments

Frappe supports:

• Single bench → multiple sites
• Separate DB per site
• Shared apps

Each site manages its own configuration through its own site_config.json.

Example structure:

sites/
├── site1.local/site_config.json
├── site2.local/site_config.json
└── site3.company.com/site_config.json

9. Adding Custom Keys to site_config.json

You can add your own keys for app-specific use.

Example:

"external_api_key": "xyzasd123"

Usage:

api_key = frappe.get_site_config().get("external_api_key")

10. Troubleshooting site_config.json

Universal Fix Commands:

bench clear-cache
bench restart

11. Advanced Settings (Used by Developers & DevOps Teams)

Force Administrator Password
“force_admin_password”: “newpassword123”

Disable File Logging
“disable_file_logging”: 1

Set Global Database Host
“db_host”: “127.0.0.1”

Configure Redis Caches
“redis_cache”: “redis://localhost:13000”

12. Cross-References (Related Frappe v15 Documentation)

• Sites in Frappe Framework
• Directory Structure Overview
• Frappe Installation & Bench Commands
• Multi-Tenant Setup Guide
• Database Configuration in Frappe

Conclusion

The site_config.json file is a foundational element of every Frappe v15 site. It defines how the site connects to its database, manages encryption, applies developer settings, controls performance limits, and handles maintenance operations. By understanding and properly managing this configuration file, developers and administrators gain full control over site behavior, security, and customization.