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
|
|
---|---|
|
Allows creating custom workers. The
|
|
If set to
|
|
Array of sentinel servers host/ip and ports |
|
Password to connect to sentinels |
|
Master service to connect to |
|
Redis master server password |
|
If set to
|
|
Array of sentinel servers host/ip and ports |
|
Password to connect to sentinels |
|
Master service to connect to |
|
Redis master server password |
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.
|
|
---|---|
|
Database Type. Options include "mariadb" and "postgres". |
|
Database Name (also used as the default database user name). |
|
Database password. |
Optional Settings
|
|
---|---|
|
Default Password for the standard "Administrator" User. This will be used as the password for the Administrator User for all new sites. |
|
Setting this allows tests to be run on this site. |
|
Enables
cross-site HTTP requests
. Can be set to:
|
|
Key used to encrypt/decrypt backups |
|
Batch Size for Data Import |
|
From v16 onwards, specify a separate DB user name |
|
Stop users from having more than one active session. |
|
Deny Multiple Sessions. |
|
If developer mode is set, DocType changes are automatically updated in files. |
|
Disables socket.io client; the client stops polling the socket.io server. |
|
Disable Error Snapshot. |
|
Disable Global Search. |
|
Disable Scheduler |
|
Disable Session Cache. |
|
Disable Website Cache. |
|
Key used to encrypt Passwords. This password is created automatically on a fresh site. Upon site restore, this key will have to be restored as well to be able to use existing passwords. |
|
If set, logs basic info from the requests and saves them under
|
|
Set the default Error Report Email. |
|
Ignore CSRF. |
|
Mention the list of apps to install at site
|
|
The host name his is required for background jobs and print to correctly identify the site URL. The value should include protocol and port (if non-default), without a trailing slash. For example:
|
|
Change the HTTP port for your Frappe Setup. |
|
Utilized in
|
|
Set Flag to allow Data from local infile for MySQL connections. |
|
Utilise frappe.debug_log via frappe.log to enable different levels of logging. At level 2, shows queries and results run at every action. |
|
Enable maintenance mode. |
|
Max file size allowed for file uploads. Default is 10MiB. |
|
Maximum number of Auto Email Reports which can be created by a user, default is 3. |
|
If set, logs all requests and saves under
|
|
Stops email sending if true. |
|
Pause Scheduler |
|
Specify Rate Limits using
|
|
Path to robots.txt file to be rendered when going to frappe-site.com/robots.txt |
|
Database root username. |
|
Database root password. |
|
Enable/Disable Server Script. |
|
Skip Setup Wizard. |
|
Specify Socket.IO Port. |
|
Generally used as fallback for conf key
|
|
Inject JavaScript script by URL in
|
|
Inject CSS Stylesheet by URL in
|
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.
|
|
---|---|
|
Database host if not
|
|
Specify port for your database. |
|
Full path to the ca.pem file used for connecting to a database host using ssl. Example value is
|
|
Full path to the cert.pem file used for connecting to a database host using ssl. Example value is
|
|
Full path to the key.pem file used for connecting to a database host using ssl. Example value is
|
|
Grant certain privileges instead of all, while setting up a Site's database. Used in
|
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 .
|
|
---|---|
|
To enable disable read from replica. Acceptable values are 1/0 or true/false. |
|
If database credentials are different on replica then set 1 else 0 |
|
IP address for repica |
|
Replica DB name |
|
Replica DB password |
Default Outgoing Email Settings
Some of the available lower level configurations for Frappe's Email module.
|
|
---|---|
|
If set, this will be the default email for outgoing mails. |
|
is used as the second preference and "notifications@example.com" is used as fallback. |
|
Use Account Email ID As Sender. |
|
Use Account Name as Sender Name |
|
Email Sender Name. |
|
SMTP server hostname. |
|
STMP port. |
|
Login id for SMTP server. |
|
Password for SMTP server. |
|
POP Timeout. |
|
Connect via SSL. |
|
Connect via TLS. |
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.
|
|
---|---|
|
Restart supervisord on bench update |
|
Restart systemd on bench update |
|
If set, the current bench will be treated purely as a tool for performing releases. |
|
Number of workers allocated for handling the background jobs. |
|
If set, turns on DNS multitenany for Bench. Used during NGINX conf generations. |
|
Port number for the File Watcher |
|
The user under which the current Bench was created. |
|
Number of Gunicorn workers. Default minimum value is 2. |
|
Number of requests after gunicorn workers will be restarted. Default value is 5000. |
|
If set, takes sites offline and stops all background processes and scheduled jobs. Used during site migrations and bench update operations. |
|
If set, pauses the scheduler for the specified sites. |
|
Port number for the redis cache process defined in the Bench Procfile. |
|
Port number for the redis queue process defined in the Bench Procfile. |
|
Port number for the redis Socket.IO process defined in the Bench Procfile. |
|
Job Scheduler runs a loop that enqueues all scheduled jobs pending execution once every scheduler_tick_interval seconds. This makes it possible to set the minimum frequency for scheduling jobs. Defaults to 60. |
|
Port number for the Socket.IO process defined in the Bench Procfile. |
|
Port number for the Frappe web server. |
|
Automatically reload Desk when assets are rebuilt. |
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
|
|
---|---|
|
Sandbox API Key |
|
Sandbox API Secret |
|
Sandbox API Password |
|
Sandbox API Username |
|
Sandbox Publishable Key |
|
Sandbox Signature |
DropBox
|
|
---|---|
|
Dropbox Access Key |
|
Dropbox Broker Site |
|
Dropbox Secret Key |
PayPal
|
|
---|---|
|
Paypal Username |
|
PayPal Password |
|
Paypal Signature |
Others
|
|
---|---|
|
Google Analytics ID |
|
Converted Rupee To Paisa for RazorPay Settings |
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)
Config |
Environment Variable |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|