couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject documentation commit: updated refs/heads/master to 0f3512b
Date Fri, 09 Sep 2016 19:38:41 GMT
Repository: couchdb-documentation
Updated Branches:
  refs/heads/master 242e4f2b8 -> 0f3512b95

feat: add single-node and cluster setup notes


Branch: refs/heads/master
Commit: 0f3512b95795887be0bac074b07148642b29067c
Parents: 242e4f2
Author: Jan Lehnardt <>
Authored: Fri Sep 9 21:38:27 2016 +0200
Committer: Jan Lehnardt <>
Committed: Fri Sep 9 21:38:27 2016 +0200

 src/cluster/setup.rst | 50 +++++++++++++++++++++++++++++++++-------------
 src/install/index.rst | 30 ++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 14 deletions(-)
diff --git a/src/cluster/setup.rst b/src/cluster/setup.rst
index eafb203..efe0671 100644
--- a/src/cluster/setup.rst
+++ b/src/cluster/setup.rst
@@ -25,7 +25,7 @@ Firewall
 If you do not have a firewall between your servers, then you can skip this.
 CouchDB in cluster mode uses the port ``5984`` just as standalone, but is also
-uses ``5986`` for the admin interface.
+uses ``5986`` for node-local APIs.
 Erlang uses TCP port ``4369`` (EPMD) to find other nodes, so all servers must be
 able to speak to each other on this port. In an Erlang Cluster, all nodes are
@@ -34,7 +34,9 @@ connected to all other nodes. A mesh.
 .. warning::
     If you expose the port ``4369`` to the Internet or any other untrusted
     network, then the only thing protecting you is the
-    :ref:`cookie <cluster/setup/cookie>`.
+    `cookie`_.
+.. _cookie:
 Every Erlang application then uses other ports for talking to each other. Yes,
 this means random ports. This will obviously not work with a firewall, but it is
@@ -143,21 +145,41 @@ Open ``sys.config``, on all nodes, and add ``inet_dist_listen_min, 9100``
-Configuration files
+.. _cluster/setup/wizard:
+The Cluster Setup Wizard
+Setting up a cluster of Erlang applications correctly can be a daunting
+task. Luckily, CouchDB 2.0 comes with a convenient Cluster Setup Wizard
+as part of the Fauxton web administration interface.
+After installation and initial startup, visit Fauxton at 
+````. You will be asked to set up
+CouchDB as a single-node instance or set up a cluster.
+When you click “setup cluster” on the other hand, 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.
+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
+per node:
+.. code-block:: shell
+    curl -X PUT<this-nodes-ip-address>/_config/admins/admin
-d '"password"'
+    curl -X PUT<this-nodes-ip-address>/_config/chttpd/bind_address
-d '""'
-.. _cluster/setup/cookie:
+Now you can enter their IP addresses in the setup screen on your first node. And make sure
to put in the admin username and password. And use the same admin username and password on
all nodes.
-Erlang Cookie
+Once you added all nodes, click “Setup” and Fauxton will finish the cluster configuration
for you.
-Open up ``vm.args`` and set the ``-setcookie`` to something secret. This must be
-identical on all nodes.
+See to get a list of all the nodes in your cluster.
-Set ``-name`` to the name the node will have. All nodes must have a unique name.
+Now your cluster is ready and available. You can send requests to any one of the nodes and
get to all the data.
+For a proper production setup, you’d now set up a HTTP proxy in front of the nodes, that
does load balancing. We recommend `HAProxy`_. See our `example configuration for HAProxy`_.
All you need is to adjust the ip addresses and ports.
-All nodes authenticates users locally, so you must add an admin user to
-local.ini on all nodes. Otherwise you will not be able to login on the cluster.
+.. _HAProxy:
+.. _example configuration for HAProxy:
\ No newline at end of file
diff --git a/src/install/index.rst b/src/install/index.rst
index d17b8c5..30afe83 100644
--- a/src/install/index.rst
+++ b/src/install/index.rst
@@ -27,6 +27,36 @@ Installation
 .. _install/cluster:
+Single Node Setup
+CouchDB 2.0 can be used in a single-node and cluster setup configuration. A single-node CouchDB
2.0 installation is what most users
+will be using. It is roughly equivalent to the CouchDB 1.x-series. Note
+that a single-node setup obviously doesn’t take any advantage of the
+new scaling and fault-tolerance features in CouchDB 2.0.
+After installation and initial startup, visit Fauxton at 
+````. You will be asked to set up
+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.
+When you run 2.0 as a single node, it doesn’t create system databases on startup. You have
to do this manually:
+.. code-block:: shell
+    curl -X PUT
+    curl -X PUT
+    curl -X PUT
+See the next section for the cluster setup instructions.
 Cluster Setup

View raw message