3.1. Introduction Into Configuring¶
3.1.1. Configuration files¶
By default, CouchDB reads configuration files from the following locations, in the following order:
All paths are specified relative to the CouchDB installation directory:
/opt/couchdb recommended on UNIX-like systems,
on Windows systems, and a combination of two directories on macOS:
Applications/Apache CouchDB.app/Contents/Resources/couchdbx-core/etc for
default.d directories, and
/Users/youruser/Library/Application Support/CouchDB2/etc/couchdb for
Settings in successive documents override the settings in earlier entries.
For example, setting the
httpd/bind_address parameter in
local.ini would override any setting in
default.ini file may be overwritten during an upgrade or
re-installation, so localised changes should be made to the
file or files within the
The configuration file chain may be changed by setting the ERL_FLAGS environment variable:
export ERL_FLAGS="-couch_ini /path/to/my/default.ini /path/to/my/local.ini"
or by placing the
-couch_ini .. flag directly in the
-couch_ini .. as a command-line argument when launching
is the same as setting the
ERL_FLAGS environment variable.
The environment variable/command-line flag overrides any
option specified in the
etc/vm.args file. And, BOTH of these
options completely override CouchDB from searching in the default
locations. Use these options only when necessary, and be sure to track
the contents of
etc/default.ini, which may change in future releases.
3.1.2. Parameter names and values¶
Parameters with value type of tuple or proplist are following the Erlang requirement for style and naming.
3.1.3. Setting parameters via the configuration file¶
The common way to set some parameters is to edit the
(location explained above).
; This is a comment [section] param = value ; inline comments are allowed
Each configuration file line may contains section definition, parameter specification, empty (space and newline characters only) or commented line. You can set up inline commentaries for sections or parameters.
The section defines group of parameters that are belongs to some specific
CouchDB subsystem. For instance,
httpd section holds not only HTTP
server parameters, but also others that directly interacts with it.
The parameter specification contains two parts divided by the equal sign
=): the parameter name on the left side and the parameter value on the
right one. The leading and following whitespace for
= is an optional to
improve configuration readability.
In case when you’d like to remove some parameter from the default.ini without modifying that file, you may override in local.ini, but without any value:
[httpd_global_handlers] _all_dbs =
This could be read as: “remove the _all_dbs parameter from the httpd_global_handlers section if it was ever set before”.
The semicolon (
;) signals the start of a comment. Everything after this
character is ignored by CouchDB.
After editing the configuration file, CouchDB should be restarted to apply any changes.
3.1.4. Setting parameters via the HTTP API¶
Alternatively, configuration parameters could be set via the HTTP API. This API allows to change CouchDB configuration on-the-fly without requiring a server restart:
curl -X PUT http://localhost:5984/_node/<name@host>/_config/uuids/algorithm -d '"random"'
In the response the old parameter’s value returns:
You should be careful with changing configuration via the HTTP API since it’s
easy to make CouchDB unavailable. For instance, if you’d like to change the
httpd/bind_address for a new one:
curl -X PUT http://localhost:5984/_node/<name@host>/_config/httpd/bind_address -d '"10.10.0.128"'
However, if you make a typo, or the specified IP address is not available
from your network, CouchDB will be unavailable for you in both cases and
the only way to resolve this will be by remoting into the server, correcting
the errant file, and restarting CouchDB. To protect yourself against such
accidents you may set the
httpd/config_whitelist of permitted
configuration parameters for updates via the HTTP API. Once this option is set,
further changes to non-whitelisted parameters must take place via the
configuration file, and in most cases, also requires a server restart before
hand-edited options take effect.