Add environment variables for cluster

[style95]

Overview

This pr is to add environment variables for CouchDB clustering.

Testing recommendations

docker run --name couchdb -d -e NUM_NODES=3 -e NUM_SHARDS=8 -e NUM_READ_QUORUM=2 -e NUM_WRITE_QUORUM=2 apache/couchdb

GitHub issue number

none

Related Pull Requests

none

Checklist

• Code is written and works correctly;
• Changes are covered by tests;
• Documentation reflects the changes;

[wohali]

This will not be merged.

The intent is that you will mount and persist the files under /opt/couchdb/etc/local.d/*. These settings, and anything else that goes in the *.ini files, can be overridden that way.

Further, the w and r parameters are deprecated as of CouchDB 2.x (they only worked in bigcouch) and have no effect anyway.

[style95]

I am not sure those parameters will be deprecated, but it seems they are not yet deprecated as we can find them in the documentation.
https://docs.couchdb.org/en/2.1.0/cluster/theory.html

Even we can override default parameters by specifying those parameters in query.
https://github.com/apache/couchdb/tree/master/src/mango#find

But if this is because document is not updated, we can just put n and q only.

This pr is just to support the case that someone want to configure those values but doesn't want to mount configuration directory.
It took similar way which is applied for $COUCHDB_USER and $COUCHDB_PASSWORD.
(https://github.com/apache/couchdb-docker/pull/32/files#diff-1fc2ace1a535d6dbd28b7b88eb11a853R41)

This could frequently happen because user can run CouchDB cluster with a single docker command.
Without this changes, user can run standalone couchDB with single docker run command, but cannot run CouchDB cluster without volume mapping.

WRT, overriding of default values, what is the preferable ways?
Since /opt/couchdb/etc/local.d/* has the highest priority, I put them there.
Configurations reside in other places such as etc/default.ini, etc/default.d/*.ini, etc/local.ini will be overridden by those in /opt/couchdb/etc/local.d/*.
(https://docs.couchdb.org/en/2.1.0/config/intro.html#configuration-files)

If this is not desired approach, kindly let me know, I can amend the commit at any times.

[wohali]

Of the four values:

• q only matters on database creation. It can be specified when doing so by adding ?q=1 to the document request.

• we STRONGLY recommend you not adjust n for clustered CouchDB setups. In fact, our cluster setup wizard sets the following values:

  • n=1 for a 1-node setup
  • n=2 for a 2-node setup (strongly not recommended)
  • n=3 for 3+ node cluster sizes

  Because it sets these values as part of the setup wizard, it will be writing the value to the last ini file in the chain. This is why mounting the /opt/couchdbetc/local.d directory externally is strongly recommended.

  Finally it's worth pointing out that even if you don't set n=1 for a single server setup, CouchDB figures out that only one node exists and creates n=1 databases in that scenario. So, again, no need to change the default here.

• The r and w parameters are definitely no longer used by CouchDB itself. I read the source code myself today to confirm this. I will open an issue to update the documentation, which is out of date.

  Yes, specifying those values as query parameters is completely different to specifying them in the ini file, where they have special meaning. You simply cannot adjust the cluster-wide r/w value as it is always calculated to be an optimal value at all times. This allows you to POST /{db}?q=1 if you want to create a q=1 database. or provide them to a document or view read.

The point I am trying to make is this: there are simply too many potential variables to be set in a clustered configuration to specify them all with environment variables. I don't see the point in special casing these variables since 99% of users will never want to change them.

[wohali]

Oh, looks like we already made the change after we landed the 2.1.0 tag:

https://docs.couchdb.org/en/latest/cluster/theory.html

and specifically:

apache/couchdb-documentation#164

[style95]

Ok I got your point.

So n will be automatically configured when setting up cluster, and q could be specified when creating database, r and w are deprecated.

Then if users want to deploy couchdb cluster without volume mapping, could they just do docker run and send cluster setup API? Then n will be automatically configured in ini file under /opt/couchdbetc/local.d?
(Though this will allow the possibility of break of cluster when restart due to missing cluster configurations)

Above situation is similar to the case of OpenWhisk.
In OpenWhisk it deploys couchdb with Ansible. I could update ansible script to always mount the configuration directory, but I want to give users more options.

[wohali]

Correct, the desired approach is to mount /opt/couchdb/etc externally to persist configuration. This approach has been documented in the updated README.