Configuration

Frappe sites can share the same application server, each behind different database solutions, configurations and locations, with different granularities via the Site Config in Bench.

The Site Config stores all site-related information, from the site's Database details to the custom domains that point to it. Through the Site Configuration, we can define the key, value pairs that may change the behaviour of Frappe and your Frappe Apps.

Site Config

site_config.json stores the global configuration for a particular site and is present in the site directory. The file is created and populated automatically by Frappe. As this depends on Frappe, the default settings or behaviour may also change depending on any updates.

{
  "db_name": "frappe_database_name",
  "db_password": "frappe_database_password",
  "admin_password": "admin_password",
}

Note: This file is considered to contain important information related to a site's state and could prove troublesome in case of loss of config files or corruption. It is backed up periodically along with the database backups in vanilla setups.

Common Site Config

common_site_config.json stores configuration shared by your bench. Actions performed at the Bench level are generally related to this config. The config keys defined may be used to alter behaviour of bench level operations or impact all the sites on your bench, considering the config value precedence.

This file is automatically generated and managed by the Bench CLI. Changes in this file may affect change in the behaviour of your Frappe setups depending on your system settings and Bench CLI's version.

{
  "background_workers": 1,
  "developer_mode": true,
  "dns_multitenant": true,
  "file_watcher_port": 6789,
  "frappe_user": "frappe",
  "gunicorn_workers": 2,
  "maintenance_mode": 0,
  "pause_scheduler": 0,
  "redis_cache": "redis://localhost:13000",
  "redis_cache_sentinel_enabled": 1,
  "redis_cache_sentinels": [
    "redis-cache-sentinel-1:26379",
    "redis-cache-sentinel-2:26379"
  ],
  "redis_cache_sentinel_password": "sentinelpassword",
  "redis_cache_master_service": "mymaster",
  "redis_cache_master_password": "masterpassword",
  "redis_queue": "redis://localhost:11000",
  "redis_queue_sentinel_enabled": 1,
  "redis_queue_sentinels": [
    "redis-queue-sentinel-1:26379",
    "redis-queue-sentinel-2:26379"
  ],
  "redis_queue_sentinel_password": "sentinelpassword",
  "redis_queue_master_service": "mymaster",
  "redis_queue_master_password": "masterpassword",
  "redis_socketio": "redis://localhost:12000",
  "scheduler_tick_interval": 120,
  "serve_default_site": true,
  "socketio_port": 9000,
  "webserver_port": 8000,
  "root_password": "MARIADB_PASSWORD",
  "live_reload": true
}

Optional Settings

Apart from this, you can set any keys you wish to be available for all sites.

Config Value Precedence

The value for a particular key being set in the site_config.json will have precedence over the value defined in the common_site_config.json. This means the key-values defined in the common config may be used as a fallback in some cases.

Imagine you want to enable the Frappe Web Logger on all the sites on your bench, except one worker.frappe.xyz because let's assume it's a very high activity site and you just don't need to be flooded with a lot of information at once. You can set enable_frappe_logger as true in the common_site_config.json and set it to false in worker.frappe.xyz's site_config.json.

$ bench config set-common-config -c enable_frappe_logger true
$ bench --site worker.frappe.xyz set-config enable_frappe_logger false

Similarly, it is possible to have a single application server to support a number of sites, each having a different database solutions provider or location. If you choose to move all the sites on your bench to another database server, the switch may be as little as updating the values in the common_site_config.json of your bench.

Standard Config Keys

These are some of the standard keys utilised by Frappe Framework and Bench.

Mandatory Settings

These keys are set in the site_config.json and are generated automatically unless the values are provided during site creation.

Optional Settings

Remote Database Host Settings

To connect to a remote database server using SSL, you must first configure the database host to accept SSL connections. An example of how to do this is available at this tutorial by Digital Ocean. After you do the configuration, set the following three options. All options must be set for Frappe to attempt to connect using SSL.

Replica Read Only Database Host Settings

Guide to setup read operations from secondary MariaDB server in a replica setup is available at in the user guides.

Default Outgoing Email Settings

Some of the available lower level configurations for Frappe's Email module.

Bench Configuration

These configurations are utilised by the Bench CLI and may be set differently for each bench on your system through the common site configuration.

Integrations

Some third party integrations may require lower level configurations you may want to define for all the sites on your bench, if you're a service provider. Frappe let's you define these config settings for your integrations via the site config.

Sandbox

DropBox

PayPal

Others

Externally extending config

Sometimes people may not want to have the values for configs like db password directly hardcoded in the site config JSON. In this case, after the site is setup normally, you can install a custom app that is allowed to extend the site configuration by returning a dict of whatever values you wish to append/overwrite. The app can fetch these however desired, but something with very low latency is preferred as it'll have to run for every request to the site.

It can be configured as such (to be done after initial site setup + installation of app)

{
    "extra_config": "vault.vault.conf_hook"
}

or if you have multiple

{
    "extra_config": ["vault.vault.conf_hook1", "vault.vault.conf_hook2"]
}

An example of the method in a custom app would be

def conf_hook() -> dict:
    password = get_password()
    return {"db_password": password}

Overriding from environment

Certain config values can be overridden via environment variables.

The priority is environment -> site config -> default value (if Frappe has one configured)