Fully document _cluster_setup endpoint for 2.1

src/api/server/common.rst

@@ -208,6 +208,126 @@
            "locations"
         ]
 
+.. _api/server/cluster_setup:
+
+===================
+``/_cluster_setup``
+===================
+
+.. versionadded: 2.0
+.. http:get:: /_cluster_setup
+    :synopsis: Return the status of the cluster setup wizard
+
+    Returns the status of the node or cluster, per the cluster setup wizard.
+
+    :<header Accept: - :mimetype:`application/json`
+                     - :mimetype:`text/plain`
+    :query array ensure_dbs_exist: List of system databases to ensure exist
+        on the node/cluster. Defaults to
+        ``["_users","_replicator","_global_changes"]``.
+    :>header Content-Type: - :mimetype:`application/json`
+                           - :mimetype:`text/plain; charset=utf-8`
+    :>json string state: Current ``state`` of the node and/or cluster (see
+        below)
+    :code 200: Request completed successfully
+
+    The ``state`` returned indicates the current node or cluster state, and
+    is one of the following:
+
+    - ``cluster_disabled``: The current node is completely unconfigured.
+    - ``single_node_disabled``: The current node is configured as a single
+      (standalone) node (``[cluster] n=1``), but either does not have a
+      server-level admin user defined, or does not have the standard system
+      databases created. If the ``ensure_dbs_exist`` query parameter is
+      specified, the list of databases provided overrides the default list
+      of standard system databases.
+    - ``single_node_enabled``: The current node is configured as a single
+      (standalone) node, has a server-level admin user defined, and has
+      the ``ensure_dbs_exist`` list (explicit or default) of databases
+      created.
+    - ``cluster_enabled``: The current node has ``[cluster] n`` > 1, is not
+      bound to ``127.0.0.1`` and has a server-level admin user defined.
+      However, the full set of standard system databases have not been
+      created yet. If the ``ensure_dbs_exist`` query parameter is
+      specified, the list of databases provided overrides the default list
+      of standard system databases.
+    - ``cluster_finished``: The current node has ``[cluster] n`` > 1, is not
+      bound to ``127.0.0.1``, has a server-level admin user defined *and*
+      has the ``ensure_dbs_exist`` list (explicit or default) of databases
+      created.
+
+    **Request**:
+
+    .. code-block:: http
+
+        GET /_cluster_setup HTTP/1.1
+        Accept: application/json
+        Host: localhost:5984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        X-CouchDB-Body-Time: 0
+        X-Couch-Request-ID: 5c058bdd37
+        Server: CouchDB/2.1.0-7f17678 (Erlang OTP/17)
+        Date: Sun, 30 Jul 2017 06:33:18 GMT
+        Content-Type: application/json
+        Content-Length: 29
+        Cache-Control: must-revalidate
+
+        {"state":"cluster_enabled"}
+
+.. http:post:: /_cluster_setup
+    :synopsis: Sets up a node as a single node or as part of a cluster.
+
+    Configure a node as a single (standalone) node, as part of a cluster,
+    or finalise a cluster.
+
+    :<header Accept: - :mimetype:`application/json`
+                     - :mimetype:`text/plain`
+    :<header Content-Type: :mimetype:`application/json`
+    :<json string action: - **enable_single_node**: Configure the current node
+                            as a single, standalone CouchDB server.
+                          - **enable_cluster**: Configure the local or remote
+                            node as one node, preparing it to be joined to a
+                            new CouchDB cluster.
+                          - **add_node**: Add the specified remote node to
+                            this cluster's list of nodes, joining it to the
+                            cluster.
+                          - **finish_cluster**: Finalise the cluster by
+                            creating the standard system databases.
+    :<json string bind_address: The IP address to which to bind the current
+        node. The special value ``0.0.0.0`` may be specified to bind to all
+        interfaces on the host. (enable_cluster and enable_single_node only)
+    :<json string username: The username of the server-level administrator to
+        create. (enable_cluster and enable_single_node only), or the remote
+        server's administrator username (add_node)
+    :<json string password: The password for the server-level administrator to
+        create. (enable_cluster and enable_single_node only), or the remote
+        server's administrator username (add_node)
+    :<json number port: The TCP port to which to bind this node
+        (enable_cluster and enable_single_node only) or the TCP port to which
+        to bind a remote node (add_node only).
+    :<json number node_count: The total number of nodes to be joined into
+        the cluster, including this one. Used to determine the value of the
+        cluster's ``n``, up to a maximum of 3. (enable_cluster only)
+    :<json string remote_node: The IP address of the remote node to setup as
+        part of this cluster's list of nodes. (enable_cluster only)
+    :<json string remote_current_user: The username of the server-level
+        administrator authorized on the remote node. (enable_cluster only)
+    :<json string remote_current_password: The password of the server-level
+        administrator authorized on the remote node. (enable_cluster only)
+    :<json string host: The remote node IP of the node to add to the cluster.
+        (add_node only)
+    :<json array ensure_dbs_exist: List of system databases to ensure exist
+        on the node/cluster. Defaults to
+        ``["_users","_replicator","_global_changes"]``.
+
+    *No example request/response included here. For a worked example, please
+    see* :ref:`cluster/setup/api`.
+
 .. _api/server/db_updates:
 
 ================

src/cluster/setup.rst

@@ -161,6 +161,8 @@ CouchDB as a single-node instance or set up a cluster.
 When you click "setup cluster" you are asked for
 admin credentials again and then to add nodes by IP address. To get
 more nodes, go through the same install procedure on other machines.
+Be sure to specify the total number of nodes you expect to add to the
+cluster before adding nodes.
 
 Before you can add nodes to form a cluster, you have to have them
 listen on a public IP address and set up an admin user. Do this, once
@@ -201,7 +203,7 @@ setup the node:
 
 .. code-block:: bash
 
-     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"}'
+     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", "node_count":"3"}'
 
 After that we can join all the nodes together. Choose one node
 as the "setup coordination node" to run all these commands on.
@@ -214,7 +216,7 @@ To add a node run these two commands:
 
 .. code-block:: bash
 
-    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", "port": 15984, "remote_node": "<remote-node-ip>", "remote_current_user": "<remote-node-username>", "remote_current_password": "<remote-node-password>" }'
+    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", "port": 15984, "node_count": "3", "remote_node": "<remote-node-ip>", "remote_current_user": "<remote-node-username>", "remote_current_password": "<remote-node-password>" }'
     curl -X POST -H "Content-Type: application/json" http://admin:password@127.0.0.1:5984/_cluster_setup -d '{"action": "add_node", "host":"<remote-node-ip>", "port": "<remote-node-port>", "username": "admin", "password":"password"}'
 
 This will join the two nodes together.

src/install/setup.rst

@@ -35,8 +35,9 @@ After installation and initial startup, visit Fauxton at
 CouchDB as a single-node instance or set up a cluster. When you click
 “Single-Node-Setup”, you will get asked for an admin username and
 password. Choose them well and remember them. You can also bind CouchDB
-to a public port, so it is accessible within your LAN or the public, if
-you are doing this on a public VM. The wizard then configures your admin
+to a public address, so it is accessible within your LAN or the public, if
+you are doing this on a public VM. Or, you can keep the installation private
+by binding only to 127.0.0.1 (localhost). The wizard then configures your admin
 username and password and creates the three system databases ``_users``,
 ``_replicator`` and ``_global_changes`` for you.
 

src/whatsnew/2.1.rst

@@ -135,6 +135,8 @@ The 2.1.0 release also includes the following minor improvements:
   * :ghissue:`483`: couchup database migration tool
   * :ghissue:`582`: Add X-Frame-Options support to help protect against
     clickjacking
+  * :ghissue:`593`: Allow bind address of 127.0.0.1 in ``_cluster_setup`` for
+    single nodes
   * :ghissue:`624`: Enable compaction daemon by default
   * :ghissue:`626`: Allow enable node decom using string "true"
   * (mango) Configurable default limit, defaults to 25.