By default, CouchDB reads configuration files from the following locations,
in the following order:

etc/default.ini

etc/default.d/*.ini

etc/local.ini

etc/local.d/*.ini

All paths are specified relative to the CouchDB installation directory:
/opt/couchdb recommended on UNIX-like systems, C:\CouchDB recommended
on Windows systems, and a combination of two directories on macOS:
Applications/ApacheCouchDB.app/Contents/Resources/couchdbx-core/etc for
the default.ini and default.d directories, and
/Users/youruser/Library/ApplicationSupport/CouchDB2/etc/couchdb for
the local.ini and local.d directories.

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.

Warning

The default.ini file may be overwritten during an upgrade or
re-installation, so localised changes should be made to the local.ini
file or files within the local.d directory.

The configuration file chain may be changed by setting the ERL_FLAGS
environment variable:

or by placing the -couch_ini.. flag directly in the etc/vm.args file.
Passing -couch_ini.. as a command-line argument when launching couchdb
is the same as setting the ERL_FLAGS environment variable.

Warning

The environment variable/command-line flag overrides any -couch_ini
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.

If there is a need to use different vm.args or sys.config files, for
example, in different locations to the ones provided by CouchDB, or you don’t
want to edit the original files, the default locations may be changed by
setting the COUCHDB_ARGS_FILE or COUCHDB_SYSCONFIG_FILE environment
variables:

The common way to set some parameters is to edit the local.ini file
(location explained above).

For example:

; 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.

Note

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:

[compactions]_default=

This could be read as: “remove the _default parameter from the
compactions 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.

If you make a typo or the specified IP address is not available from your
network, CouchDB will be unreachable. The only way to resolve this will be
to remote into the server, correct the config file, and restart 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, will also require a server restart before taking effect.

While the HTTP API allows configuring all nodes in the
cluster, as a convenience, you can use the literal string _local in place
of the node name, to interact with the local node’s configuration. For
example: