couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <>
Subject Setting up CouchDB 2.0
Date Wed, 24 Sep 2014 10:35:50 GMT
# Setting up CouchDB 2.0

Hey all, since we are getting close to feature completeness, I’d like to bring up the topic
of setting up CouchDB 2.0 solo and as a cluster. Actually, Bob Newson brought this up on IRC,
and we discussed it a bit and I agreed to write up our current thoughts. As usual, please
be generous with your commentary :)

Here is what we envision (includes feedback by rnewson, chewbranca and davisp). This needs
to be squared against current implementation (, required
engineering and security considerations.

My main motivation is to make sure that CouchDB 2.0 is as simple to use as CouchDB 1.0. Because
setting up a cluster is intrinsically more complicated than launching a single node, this
isn’t quite possible, but I believe it is crucial to make this as simple as it can be made.

The current setup procedure (again, at is not terribly hard,
but I think we can do better.

## The Setup Procedure

Here is a preliminary outline of how we thing this could go. It is still very high-level,
but should give you the idea. If you see any technical or security roadblocks that could make
this hard to actually build, please holler :)

N. End User Action
  - what happens behind the scenes

1. User sets up a new CouchDB 2.0 (A), starts it and goes to Faxuton
    - `couchdb` prompts for admin user and pass, if none are configured, rejects startup without

2. Fauxton sees that it has no nodes connected to it yet (/nodes db empty or non existent),
so Fauxton shows a cluster setup screen (that we can go back later as well).
    - *handwaving* something about a /_membership endpoint that I don’t know much about,
2.1. If the user just wants a single node couch, there is a button “Thanks no cluster setup
needed” and we go directly to step 5.

3. User sets up another CouchDB 2.0 (B) and notes its fully qualified domain name or ip address
  - and uses the same admin/pass combo as on node A.

4. User goes back to Fauxton on A and adds a node in the (fictitious at this point) UI and
enters node B’s fqdn/ip
  - Fauxton posts this info to e.g. /_setup on A, A then checks if the node fqdn/ip is reachable,
if not, returns an error, if yes, it creates the node doc in /nodes
  - The post to /_setup also configures the erlang cookie/shared secret (this requires code
that updates a shared cookie value (could be a UUID, or readable-secure random password) but
results in really nice end-user friendliness). This enables secure Erlang-level communication
that the cluster needs to do its work, without any end-user interaction.
  - a security consideration here is that a node is open to receive a shared secret via HTTP,
someone might be able to hijack an in-setup cluster node, requiring an admin/pass on node-startup
and making the /_setup endpoint admin-only should mitigate that.

// Repeat steps 3. and 4. until all nodes are added

5. User clicks a “cluster setup done” button and goes back to the regular Fauxton start
  - fauxton posts to /_setup with a body that indicates that the setup is complete and node
A creates /_users and /_replicator and whatever else is needed) in the cluster, to get it
into a production-ready state (*waves hands*)
  - this could also flip a bit “cluster setup done” in all nodes, not yet sure what we’d
use this for, though, maybe block all non-fauxton/setup traffic until setup is done.

There is some handwaving how the adding-nodes machinery works under the hood, but I think
that can be worked out later.

## Requirements

This requires at least a new HTTP endpoint /_setup which needs to be defined in a little more
detail. I might give it a stab later.

This also requires a start script that knows how to read a username and password from the
command line (for interactive setups) or from a config file or environment vars (for automated

This finally requires a Fauxton addition that makes /_setup accessible to users.

I think the engineering effort is small enough to warrant the “expense” of having a really
nice user experience for CouchDB 2.0.

### A note on admin party

Admin party has to go. It is the right thing to do to keep a node or a cluster in a “vulnerable
setup state” as short as possible. As outlined above, a node would not even start with out
an admin set up, and creating an admin user can be made super simple, so it doesn’t inhibit
the setup user experience too much (we’ve done the same thing at Hoodie, and it works really
well). This will also give us some more “doing it right” credibility among the folks who
care about these things (c.f. turning off delayed commits).

That’s it so far, what do you think? :)


View raw message