Improve CouchDB setup documentation, esp. for clustering

apache · Nov 19, 2018 · 0828bc5 · 0828bc5
1 parent 9015f03
commit 0828bc5
Show file tree

Hide file tree

Showing 15 changed files with 435 additions and 326 deletions.
diff --git a/src/cluster/index.rst b/src/cluster/index.rst
@@ -16,17 +16,16 @@
 Cluster Reference
 =================
 
-As of 2.0 CouchDB now have two modes of operations:
+As of CouchDB 2.0.0, CouchDB can be run in two different modes of operation:
     * Standalone
     * Cluster
 
-This part of the documentation is about setting up and maintain a CouchDB
-cluster.
+This section details the theory behind CouchDB clusters, and provides specific
+operational instructions on node, database and shard management.
 
 .. toctree::
     :maxdepth: 2
 
-    setup
     theory
     nodes
     databases

diff --git a/src/cluster/setup.rst b/src/cluster/setup.rst
diff --git a/src/index.rst b/src/index.rst
@@ -26,6 +26,7 @@ Table of Contents
 
     intro/index
     install/index
+    setup/index
     config/index
     replication/index
     maintenance/index

diff --git a/src/install/docker.rst b/src/install/docker.rst
@@ -32,8 +32,8 @@ use of a Docker volume for data at ``/opt/couchdb/data``.
 Note that you can also use the ``NODENAME`` environment variable to set the
 name of the CouchDB node inside the container.
 
-**Be sure to complete the** :ref:`First-time Setup <install/setup>` **steps for
-a single node or clustered installation.**
+**Your installation is not complete. Be sure to complete the**
+:ref:`Setup <setup>` **steps for a single node or clustered installation.**
 
 Further details on the Docker configuration are available in our
 `couchdb-docker git repository`_.

diff --git a/src/install/freebsd.rst b/src/install/freebsd.rst
@@ -52,8 +52,8 @@ Administrators should use ``default.ini`` as reference and only modify the
 
 Post install
 ------------
-**Be sure to complete the** :ref:`First-time Setup <install/setup>` **steps for
-a single node or clustered installation.**
+**Your installation is not complete. Be sure to complete the**
+:ref:`Setup <setup>` **steps for a single node or clustered installation.**
 
 In case the install script fails to install a non-interactive user "couchdb" to
 be used for the database, the user needs to be created manually:

diff --git a/src/install/index.rst b/src/install/index.rst
@@ -12,9 +12,9 @@
 
 .. _install:
 
-===============================
-Installation & First-Time Setup
-===============================
+============
+Installation
+============
 
 .. toctree::
     :maxdepth: 2
@@ -25,6 +25,5 @@ Installation & First-Time Setup
     freebsd
     docker
     snap
-    setup
     upgrading
     troubleshooting
diff --git a/src/install/mac.rst b/src/install/mac.rst
@@ -37,8 +37,8 @@ That's all, now CouchDB is installed on your Mac:
 #. Run Apache CouchDB application
 #. `Open up Fauxton`_, the CouchDB admin interface
 #. Verify the install by clicking on `Verify`, then `Verify Installation`.
-#. **Be sure to complete the** :ref:`First-time Setup <install/setup>` **steps
-   for a single node or clustered installation.**
+#. **Your installation is not complete. Be sure to complete the**
+   :ref:`Setup <setup>` **steps for a single node or clustered installation.**
 #. Time to Relax!
 
 .. _Open up Fauxton: http://localhost:5984/_utils

diff --git a/src/install/snap.rst b/src/install/snap.rst
@@ -30,9 +30,11 @@ After `installing snapd`_, the CouchDB snap can be installed via::
 CouchDB will be installed at ``/snap/couchdb``. Data will be stored at
 ``/var/snap/couchdb/``.
 
-.. _installing snapd: https://snapcraft.io/docs/core/install
+**Your installation is not complete. Be sure to complete the**
+:ref:`Setup <setup>` **steps for a single node or clustered installation.**
 
 Further details on the snap build process are available in our
 `couchdb-pkg git repository`_.
 
+.. _installing snapd: https://snapcraft.io/docs/core/install
 .. _couchdb-pkg git repository: https://github.com/apache/couchdb-pkg
diff --git a/src/install/troubleshooting.rst b/src/install/troubleshooting.rst
@@ -141,7 +141,7 @@ Quick Build
 Having problems getting CouchDB to run for the first time? Follow this simple
 procedure and report back to the user mailing list or IRC with the output
 of each step. Please put the output of these steps into a paste service (such
-as https://paste.apache.org/) rather than including the output of your entire
+as https://paste.ee/) rather than including the output of your entire
 run in IRC or the mailing list directly.
 
 1. Note down the name and version of your operating system and your processor
@@ -183,7 +183,7 @@ run in IRC or the mailing list directly.
 Upgrading
 =========
 
-Are you upgrading from CouchDB 2.0? Install CouchDB into a fresh directory.
+Are you upgrading from CouchDB 1.x? Install CouchDB into a fresh directory.
 CouchDB's directory layout has changed and may be confused by libraries
 present from previous releases.