Improve installation and initial setup documentation

[wohali]

I've fielded quite a few questions on this recently in IRC/Slack. Here's what I want to do:

1. Fix the navigation in the docs so that it's clear single-node setups need to manually PUT _users and _replicator to get a single node working right. Right now sections 2.5 and 2.6 are on the same page as the TOC for chapter 2, so they are easily overlooked.
2. Make it clear that _global_changes is optional and not required unless you need the functionality
3. Add callouts to the new packages for Debian, Ubuntu, CentOS and snaps; add references to FreeBSD/NetBSD, Windows packages, etc. List these above the "Compiling from source" section.

[ArchangeGabriel]

One other thing that you should put there: how do I setup a single node using cli? I’ve seen this for cluster:

 curl -X POST -H "Content-Type: application/json" http://admin:password@127.0.0.1:5984/_cluster_setup -d '{"action": "enable_cluster", "bind_address":"0.0.0.0", "username": "admin", "password":"password"}'

But what about single node?

[ArchangeGabriel]

Let’s be more precise:

– In 1.6, I could setup a single node from CLI:
curl -s -X PUT 127.0.0.1:5984/_config/admins/<user> -d "\"<password>\""

– How to do this in 2.0? Browsing the web interface at http://127.0.0.1:5984/_utils/#setup, I first have to click on “Configure Single Node”, then I’m on http://127.0.0.1:5984/_utils/#setup/singlenode where I need to set username, password, bind_address and port before validating through “Configure Node”. How do I do that using the CLI?

Thanks

[wohali]

Technically none of the things you mention are required to set up a single node from the CLI if you don't want to change the address, port, or create an admin user. But I'll include the steps to set up a single node from the CLI beyond what's in there.

The initial rework is done, though: see http://docs.couchdb.org/en/latest/install/setup.html

[ArchangeGabriel]

OK, but I indeed want to create an admin user. (Default address is 127.0.0.1, right? Else I would have to change it)

Also currently if you want to setup an admin this way, you’re forced to bind to something else than 127.0.0.1 (apache/couchdb-fauxton#874), though you can change that from the config afterward (in /etc/couchdb/local.ini for my case). Is adding an admin to this config file the same as through the interface? This could be a workaround for my case.

[wohali]

You can still curl -X PUT 127.0.0.1:5984/_node/couchdb@localhost/_config/admins/<user> -d "\"<password>\"" to create an admin. The URL has changed because node-specific operations require a prefix to determine which node you're talking to in a cluster. (Technically, "standalone single-node" mode is just a cluster of one node.)

You can also just add this block to your local.ini file (or any file in etc/local.d named <something>.ini):

[admins]
admin = password

and restart CouchDB to get it to hash the password.

We'll look at improving the _cluster_setup endpoint to support binding a single node to 127.0.0.1 It's currently disallowed because it's designed to set up clusters, and that's not allowed in clustered setup.

[wohali]

(1) is done. (2) will land shortly. (3) I will split into a new issue.

[wohali]

(2) is landed. I am closing this and opening a new issue for (3).

[ArchangeGabriel]

Those updates made me realize I forgot to thank you for the curl -X PUT 127.0.0.1:5984/_node/couchdb@localhost/_config/admins/<user> -d "\"<password>\"" command. So thanks!

[jareware]

Also, just in case someone finds themselves here looking for the magic HTTP API command to start a newly-spun-up CouchDB container in single-node mode:

curl -X POST -H "Content-Type: application/json" http://admin:password@localhost:5984/_cluster_setup -d '{"action": "enable_single_node"}'

[wohali]

Thanks @jareware , this is in our documentation here:

http://docs.couchdb.org/en/latest/api/server/common.html#post--_cluster_setup

[ArchangeGabriel]

@jareware: Thanks for this!
@wohali: This specific line could be in http://docs.couchdb.org/en/latest/install/setup.html#single-node-setup though.