couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <>
Subject Re: Setting up CouchDB 2.0
Date Wed, 24 Sep 2014 14:25:49 GMT

On 24 Sep 2014, at 16:15 , Dale Harvey <> wrote:

> On 24 September 2014 15:12, Jan Lehnardt <> wrote:
>> On 24 Sep 2014, at 13:26 , Alexander Shorin <> wrote:
>>> Hi Jan,
>>> Looks good, replied inline.
>>> On Wed, Sep 24, 2014 at 2:35 PM, Jan Lehnardt <> wrote:
>>>> # 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
>>> I think password MUST be set manually in config file. Otherwise this
>>> will be nothing different from Admin Party when there is a race
>>> condition: who opens Fauxton first wins.
>> `couchdb` is a shell script that runs before Erlang is booted up, so
>> there is no race condition.
>>>> 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, yet.
>>>> 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 (fqdn/ip)
>>>> - 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 page.
>>>> - 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.
>>> Too much magic is applied for /_setup.
>> It is not well defined yet, yes, but too much magic? Let’s design it and
>> decide then :)
>> Also what would you do alternatively?
>>> Is it the only resource which will verify availability of the node to
>> add?
>> Possibly, what other resources would you want to have to expose this
>> information?
>>> Can I run setup once again right after it is done?
>> Unspecified as per now, but I’d imagine you can. All /_setup does is doing
>> in bulk what tells you to do manually
>> today.
>>> How can I rollback my cluster CouchDB to single node?
>> Can you do this today? Is this a feature we want?
> I am not so worried about rolling back (although I definitely think its a
> feature clustered users will want)
> But I do think there needs to be an experience that matches todays
> "./utils/run | couchdb" in which I can just ./start_couchdb and have it
> working, whether it requires admin credentials on startup or not I am not
> so worried about, but I do think its very important to have start path that
> allows users to completely ignore cluster setup if they dont want it.

Fully agreed! The current proposal still requires the end user to go
to Fauxton to say “no cluster please, thank you”, but that could be
translated to a hypothetical `couchdb --nocluster` or something.

`./utils/run` or somesuch I think we’ll always have for dev reasons.


>>> And can I run setup again after that?
>> Again unspecified, see above.
>>> Can I protect my instance from being included into cluster by some other
>> node?
>> Yes, e.g. don’t give the other node admin creds. Is this enough? I don’t
>> know. Maybe /_setup is also disabled after the “the cluster is ready” bit
>> was flipped and you need to disable that that manually again, to get access
>> to /_setup again.
>>> Also, UI-less setup also requires and probably it have to be the base
>>> for Fauxton UI workflow.
>> As I said in my reply to Dirkjan, that was my intention.
>>>> ## 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 setups).
>>>> 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).
>>> Wouldn't it cause "false protection" problem? If user need just a
>>> database that works for local need without auth headaches forcing him
>>> to set some password will make him set something trivial like "123",
>>> "qwerty", "god", "sex", "love" etc. Yay, user has admin now, but does
>>> such admin protects instance or makes a feel that instance is
>>> protected? What if we keep Admin Party as an option, but disabled by
>>> default? For sure, only for single node mode. Too complicated?
>> This is a good point. As mentioned in my other email, I’m living in
>> forced-admin Couch land at the moment, and all my personal test setups have
>> the same three letter password. But I know it’s there and I know it is not
>> secure. The fact that I took a deliberate shortcut there makes me remember
>> to pick a proper password when setting up a CouchDB for production. So
>> there is that.
>> My goal was to make the cluster setup as easy as possible. Whether or not
>> admin party plays a role is kinda orthogonal to this, but it was worth
>> mentioning, since removing it has been discussed in the past. I’m happy to
>> ignore the admin party discussion for now in favour of defining the first
>> run experience for solo and cluster setups.
>> Best
>> Jan
>> --
>>>> That’s it so far, what do you think? :)
>>>> Best
>>>> Jan
>>>> --
>>> --
>>> ,,,^..^,,,

View raw message