default.d and local.d posted Tuesday, October 27, 2020 by The Neighbourhoodie CouchDB Team
When we explored how default.ini and local.ini work in unison to provide a coherent configuration and upgrade behaviour, we skipped over one more part of the configuration puzzle.
In addition to the two configuration files you are already familiar with, CouchDB can be configured with two further configuration directories, which in turn can hold multiple configuration files each.
First, we explain why this mechanism exists, and then we go into the details of how this works. One thing up front however, this all is entirely optional, so if you have no need for this, you are free to ignore everything you read here.
What problem does this additional way to provide configuration files solve?
CouchDB is usually delivered in one piece, a so called release, that includes everything that makes up CouchDB. Most likely, that’s what you’re running too.
However, there is a tiny number of extensions to CouchDB that are not part of the main release. In the past this has been an extension to provide fulltext search to CouchDB, but this has since been integrated. Very specialised users of CouchDB might have their own extensions that are not public.
Those extensions often have a need to be configured. And just like CouchDB, they might ship with a default configuration, and they have a place to make local changes to the default configuration. Each extension can have a file in both directories each to mirror the behaviour of default.ini and local.ini. For example:
/etc/couchdb/default.d/search.ini/etc/couchdb/local.d/search.ini
You would receive the default configuration in the first file, and you can make local changes in the second file. When installing new versions, new default configuration options can be added to default.d/search.ini, and as such, this file would be overwritten during an upgrade. local.d/search.ini however will not be overwritten and retain all local changes across software updates.
In addition, the standard Linux packages for CouchDB often place files inside of the default.d directory, to make changes that are distribution-specific. As an example, the Debian installer adds a file that redirects log files to /var/log/couchdb/couchdb.log. It also places settings related to the installation prompts in default.d/10-bind-address.ini or default.d/5-single-node.ini, depending on the settings chosen at installation time.