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



workers

Allows creating custom workers. The background_workers param is optional, if not set the general background_workers will be used. Example: "workers": { "custom_worker1": { "timeout": 5000, "background_workers": 4 } } . Regenerate config and restart processes to take effect.

redis_cache_sentinel_enabled

If set to 1 connects to Redis sentinel in production setup

redis_cache_sentinels

Array of sentinel servers host/ip and ports

redis_cache_sentinel_password

Password to connect to sentinels

redis_cache_master_service

Master service to connect to

redis_cache_master_password

Redis master server password

redis_queue_sentinel_enabled

If set to 1 connects to Redis sentinel in production setup

redis_queue_sentinels

Array of sentinel servers host/ip and ports

redis_queue_sentinel_password

Password to connect to sentinels

redis_queue_master_service

Master service to connect to

redis_queue_master_password

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.



db_type

Database Type. Options include "mariadb" and "postgres".

db_name

Database Name (also used as the default database user name).

db_password

Database password.

Optional Settings



admin_password

Default Password for the standard "Administrator" User. This will be used as the password for the Administrator User for all new sites.

allow_tests

Setting this allows tests to be run on this site.

allow_cors

Enables cross-site HTTP requests . Can be set to:

  • a specific origin, for example: "https://example.com"

  • a list of origins, for example: ["https://portal.example.com", "https://shop.example.com"]

  • a wildcard: "*" (Not recommended for production use)

backup_encryption_key

Key used to encrypt/decrypt backups

data_import_batch_size

Batch Size for Data Import

db_user

From v16 onwards, specify a separate DB user name

deny_multiple_logins

Stop users from having more than one active session.

deny_multiple_sessions

Deny Multiple Sessions.

developer_mode

If developer mode is set, DocType changes are automatically updated in files.

disable_async

Disables socket.io client; the client stops polling the socket.io server.

disable_error_snapshot

Disable Error Snapshot.

disable_global_search

Disable Global Search.

disable_scheduler

Disable Scheduler

disable_session_cache

Disable Session Cache.

disable_website_cache

Disable Website Cache.

encryption_key

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.

enable_frappe_logger

If set, logs basic info from the requests and saves them under ./sites/{site}/logs/frappe.web.log .

error_report_email

Set the default Error Report Email.

ignore_csrf

Ignore CSRF.

install_apps

Mention the list of apps to install at site restore , reinstall and on new creations.

host_name

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: "https://erp.example.org:2424"

http_port

Change the HTTP port for your Frappe Setup.

keep_backups_for_hours

Utilized in frappe.utils.new_backup to pass through frappe.utils.delete_temp_backups . It retains the backup files depending on their age in hours.

local_infile

Set Flag to allow Data from local infile for MySQL connections.

logging

Utilise frappe.debug_log via frappe.log to enable different levels of logging. At level 2, shows queries and results run at every action.

maintenance_mode

Enable maintenance mode.

max_file_size

Max file size allowed for file uploads. Default is 10MiB.

max_reports_per_user

Maximum number of Auto Email Reports which can be created by a user, default is 3.

monitor

If set, logs all requests and saves under ./logs/monitor.json.log . Check out monitoring under the Debugging documentation.

mute_emails

Stops email sending if true.

pause_scheduler

Pause Scheduler

rate_limit

Specify Rate Limits using frappe.rate_limiter . Check out the document reference rate limiting .

robots_txt

Path to robots.txt file to be rendered when going to frappe-site.com/robots.txt

root_login

Database root username.

root_password

Database root password.

server_script_enabled

Enable/Disable Server Script.

skip_setup_wizard

Skip Setup Wizard.

socketio_port

Specify Socket.IO Port.

webserver_port

Generally used as fallback for conf key http_port .

app_include_js

Inject JavaScript script by URL in /app . Must be a list of absolute URLs.

app_include_css

Inject CSS Stylesheet by URL in /app . Must be a list of absolute URLs.

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.



db_host

Database host if not localhost .

db_port

Specify port for your database.

db_ssl_ca

Full path to the ca.pem file used for connecting to a database host using ssl. Example value is "/etc/mysql/ssl/ca.pem" .

db_ssl_cert

Full path to the cert.pem file used for connecting to a database host using ssl. Example value is "/etc/mysql/ssl/client-cert.pem" .

db_ssl_key

Full path to the key.pem file used for connecting to a database host using ssl. Example value is "/etc/mysql/ssl/client-key.pem" .

rds_db

Grant certain privileges instead of all, while setting up a Site's database. Used in db_manager.py .

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 .



read_from_replica

To enable disable read from replica. Acceptable values are 1/0 or true/false.

different_credentials_for_replica

If database credentials are different on replica then set 1 else 0

replica_host

IP address for repica

replica_db_name

Replica DB name

replica_db_password

Replica DB password

Default Outgoing Email Settings

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



auto_email_id

If set, this will be the default email for outgoing mails.

mail_login

is used as the second preference and "notifications@example.com" is used as fallback.

always_use_account_email_id_as_sender

Use Account Email ID As Sender.

always_use_account_name_as_sender_name

Use Account Name as Sender Name

email_sender_name

Email Sender Name.

mail_server

SMTP server hostname.

mail_port

STMP port.

mail_login

Login id for SMTP server.

mail_password

Password for SMTP server.

pop_timeout

POP Timeout.

use_ssl

Connect via SSL.

use_tls

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_supervisor_on_update

Restart supervisord on bench update

restart_systemd_on_update

Restart systemd on bench update

release_bench

If set, the current bench will be treated purely as a tool for performing releases.

background_workers

Number of workers allocated for handling the background jobs.

dns_multitenant

If set, turns on DNS multitenany for Bench. Used during NGINX conf generations.

file_watcher_port

Port number for the File Watcher

frappe_user

The user under which the current Bench was created.

gunicorn_workers

Number of Gunicorn workers. Default minimum value is 2.

gunicorn_max_requests

Number of requests after gunicorn workers will be restarted. Default value is 5000.

maintenance_mode

If set, takes sites offline and stops all background processes and scheduled jobs. Used during site migrations and bench update operations.

pause_scheduler

If set, pauses the scheduler for the specified sites.

redis_cache

Port number for the redis cache process defined in the Bench Procfile.

redis_queue

Port number for the redis queue process defined in the Bench Procfile.

redis_socketio

Port number for the redis Socket.IO process defined in the Bench Procfile.

scheduler_tick_interval

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.

socketio_port

Port number for the Socket.IO process defined in the Bench Procfile.

webserver_port

Port number for the Frappe web server.

live_reload

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 Key

sandbox_api_secret

Sandbox API Secret

sandbox_api_password

Sandbox API Password

sandbox_api_username

Sandbox API Username

sandbox_publishable_key

Sandbox Publishable Key

sandbox_signature

Sandbox Signature

DropBox



dropbox_access_key

Dropbox Access Key

dropbox_broker_site

Dropbox Broker Site

dropbox_secret_key

Dropbox Secret Key

PayPal



paypal_username

Paypal Username

paypal_password

PayPal Password

paypal_signature

Paypal Signature

Others



google_analytics_id

Google Analytics ID

converted_rupee_to_paisa

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

redis_queue

FRAPPE_REDIS_QUEUE

redis_cache

FRAPPE_REDIS_CACHE

db_type

FRAPPE_DB_TYPE

db_socket

FRAPPE_DB_SOCKET

db_host

FRAPPE_DB_HOST

db_port

FRAPPE_DB_PORT

db_user

FRAPPE_DB_USER

db_name

FRAPPE_DB_NAME

db_password

FRAPPE_DB_PASSWORD

On this page