You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2017/07/30 07:55:37 UTC
[couchdb-documentation] branch 593-setup-wizard updated (84cdce3 ->
a2d26bc)
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a change to branch 593-setup-wizard
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.
omit 84cdce3 Fully document _cluster_setup endpoint for 2.1
new a2d26bc Fully document _cluster_setup endpoint for 2.1
This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version. This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:
* -- * -- B -- O -- O -- O (84cdce3)
\
N -- N -- N refs/heads/593-setup-wizard (a2d26bc)
You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.
Any revisions marked "omit" are not gone; other references still
refer to them. Any revisions marked "discard" are gone forever.
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/whatsnew/2.1.rst | 2 ++
1 file changed, 2 insertions(+)
--
To stop receiving notification emails like this one, please contact
['"commits@couchdb.apache.org" <co...@couchdb.apache.org>'].
[couchdb-documentation] 01/01: Fully document _cluster_setup
endpoint for 2.1
Posted by wo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch 593-setup-wizard
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit a2d26bcac375f873b1bc618c69138a07b4eff3e9
Author: Joan Touzet <jo...@atypical.net>
AuthorDate: Sun Jul 30 03:51:05 2017 -0400
Fully document _cluster_setup endpoint for 2.1
---
src/api/server/common.rst | 121 ++++++++++++++++++++++++++++++++++++++++++++++
src/cluster/setup.rst | 13 ++++-
src/install/setup.rst | 5 +-
src/whatsnew/2.1.rst | 2 +
4 files changed, 137 insertions(+), 4 deletions(-)
diff --git a/src/api/server/common.rst b/src/api/server/common.rst
index ee0f352..96afc43 100644
--- a/src/api/server/common.rst
+++ b/src/api/server/common.rst
@@ -208,6 +208,127 @@
"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 value for the cluster's ``n`` value, *i.e.*
+ the number of replicas of each document to store. Specify ``2`` for
+ a 2-node cluster, and ``3`` for any cluster of 3 or more nodes.
+ (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:
================
diff --git a/src/cluster/setup.rst b/src/cluster/setup.rst
index 031a028..3026a3d 100644
--- a/src/cluster/setup.rst
+++ b/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,14 @@ 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"}'
+
+.. warning::
+ The ``node_count`` parameter is used to set the ``[cluster]`` ``n`` value.
+ Even when joining more than 3 nodes into a cluster using this endpoint,
+ it is **strongly** recommended not to set this value higher than 3, as
+ it will directly impact the number of replicas of each document in the
+ cluster.
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 +223,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.
diff --git a/src/install/setup.rst b/src/install/setup.rst
index 8bcc8d3..6cd3861 100644
--- a/src/install/setup.rst
+++ b/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.
diff --git a/src/whatsnew/2.1.rst b/src/whatsnew/2.1.rst
index 0af53f0..71e850f 100644
--- a/src/whatsnew/2.1.rst
+++ b/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.
--
To stop receiving notification emails like this one, please contact
"commits@couchdb.apache.org" <co...@couchdb.apache.org>.