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/05/29 01:23:19 UTC
[couchdb-documentation] branch master updated: Document new couchup
utility, improve installation documentation
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new bee20af Document new couchup utility, improve installation documentation
bee20af is described below
commit bee20af874ea4e5306e2f8755e1292329e24d3b5
Author: Joan Touzet <jo...@atypical.net>
AuthorDate: Sun May 28 04:09:58 2017 -0400
Document new couchup utility, improve installation documentation
This adds documentation for the new couchup utility. It also reorganizes
the installation documentation order, and includes explicit reminders
in every installation section to follow the first-time setup steps.
We've been getting a LOT of drive-bys on IRC/Slack asking why there are
endless errors about _users and _replicator in the logfiles, and I
suspect it's because that section is buried on the same page as the table
of contents for the installation section.
---
src/install/freebsd.rst | 3 ++
src/install/index.rst | 50 +++------------------
src/install/mac.rst | 2 +
src/install/setup.rst | 64 +++++++++++++++++++++++++++
src/install/unix.rst | 3 +-
src/install/upgrading.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++++
src/install/windows.rst | 3 +-
7 files changed, 187 insertions(+), 47 deletions(-)
diff --git a/src/install/freebsd.rst b/src/install/freebsd.rst
index dc749bf..88c6728 100644
--- a/src/install/freebsd.rst
+++ b/src/install/freebsd.rst
@@ -52,6 +52,9 @@ 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.**
+
In case the install script fails to install a noninteractive 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
index 6dfa9da..26751ff 100644
--- a/src/install/index.rst
+++ b/src/install/index.rst
@@ -12,9 +12,9 @@
.. _install:
-============
-Installation
-============
+===============================
+Installation & First-Time Setup
+===============================
.. toctree::
:maxdepth: 2
@@ -23,46 +23,6 @@ Installation
windows
mac
freebsd
+ setup
+ upgrading
troubleshooting
-
-.. _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
-``http://127.0.0.01:5984/_utils#setup``. 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. The wizard then configures
-your admin username and password and creates the three system databases
-_users, _replicator and _global_changes for you.
-
-Alternatively, if you don't want to use the “Single-Node-Setup” wizard
-and run 2.0 as a single node with admin username and password already
-configured make sure to create the three three system databases
-manually on startup:
-
-.. code-block:: sh
-
- curl -X PUT http://127.0.0.1:5984/_users
-
- curl -X PUT http://127.0.0.1:5984/_replicator
-
- curl -X PUT http://127.0.0.1:5984/_global_changes
-
-See the next section for the cluster setup instructions.
-
-Cluster Setup
-=============
-
-See the :ref:`Cluster Reference <cluster>` for details.
diff --git a/src/install/mac.rst b/src/install/mac.rst
index 7f9f822..68fe8fd 100644
--- a/src/install/mac.rst
+++ b/src/install/mac.rst
@@ -37,6 +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.**
#. Time to Relax!
.. _Open up Fauxton: http://localhost:5984/_utils
diff --git a/src/install/setup.rst b/src/install/setup.rst
new file mode 100644
index 0000000..3443612
--- /dev/null
+++ b/src/install/setup.rst
@@ -0,0 +1,64 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _install/setup:
+
+================
+First-Time Setup
+================
+
+CouchDB 2.0 can be used in a single-node or clustered configuration.
+Below are the first-time setup steps required for each of these
+configurations.
+
+.. _install/setup/single:
+
+Single Node Setup
+=================
+
+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
+``http://127.0.0.01:5984/_utils#setup``. 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. The wizard then configures your admin
+username and password and creates the three system databases _users,
+_replicator and _global_changes for you.
+
+Alternatively, if you don't want to use the “Single-Node-Setup” wizard
+and run 2.0 as a single node with admin username and password already
+configured, make sure to create the three three system databases manually
+on startup:
+
+.. code-block:: sh
+
+ curl -X PUT http://127.0.0.1:5984/_users
+
+ curl -X PUT http://127.0.0.1:5984/_replicator
+
+ curl -X PUT http://127.0.0.1:5984/_global_changes
+
+See the next section for the cluster setup instructions.
+
+.. _install/setup/cluster:
+
+Cluster Setup
+=============
+
+As configuration has many steps, see the :ref:`Cluster Reference Setup
+<cluster/setup>` for full details.
diff --git a/src/install/unix.rst b/src/install/unix.rst
index 2870391..62578cc 100644
--- a/src/install/unix.rst
+++ b/src/install/unix.rst
@@ -236,7 +236,8 @@ From here you should verify your installation by pointing your web browser to::
http://localhost:5984/_utils/index.html#verifyinstall
-Finally, to configure your cluster see :ref:`cluster/setup/wizard`.
+**Be sure to complete the** :ref:`First-time Setup <install/setup>` **steps for
+a single node or clustered installation.**
Running as a Daemon
===================
diff --git a/src/install/upgrading.rst b/src/install/upgrading.rst
new file mode 100644
index 0000000..179d49d
--- /dev/null
+++ b/src/install/upgrading.rst
@@ -0,0 +1,109 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _install/upgrading:
+
+==========================
+Upgrading from CouchDB 1.x
+==========================
+
+CouchDB 2.x fully supports upgrading from CouchDB 1.x. A data migration
+process is required to use CouchDB 1.x databases in CouchDB 2.x. CouchDB
+2.1 supplies a utility, ``couchup``, to simplify the migration process.
+
+``couchup`` utility
+===================
+
+The ``couchup`` utility is a Python script that supports listing CouchDB
+1.x databases on a CouchDB 2.x installation, migrating them for use with
+CouchDB 2.x, rebuilding any database views after migration, and deleting
+the 1.x databases once migration is complete.
+
+``couchup`` runs under Python 2.7 or 3.x, and requires the Python
+`requests library <http://python-requests.org/>`_, and can optionally
+make use of the Python `progressbar library
+<https://pypi.python.org/pypi/progressbar>`_.
+
+Overview
+--------
+
+couchup makes it easy to migrate your CouchDB 1.x databases to CouchDB
+2.x by providing useful 4 sub-commands:
+
+* ``list`` - lists all CouchDB 1.x databases
+* ``replicate`` - replicates one or more 1.x databases to CouchDB 2.x
+* ``rebuild`` - rebuilds one or more CouchDB 2.x views
+* ``delete`` - deletes one or more CouchDB 1.x databases
+
+Once you have installed CouchDB 2.x, copy the .couch files from
+your 1.x installation (or, if you've upgraded in-place, do nothing),
+then use commands similar to the following:
+
+.. code-block:: bash
+
+ $ couchup list # Shows your unmigrated 1.x databases
+ $ couchup replicate -a # Replicates your 1.x DBs to 2.x
+ $ couchup rebuild -a # Optional; starts rebuilding your views
+ $ couchup delete -a # Deletes your 1.x DBs (careful!)
+ $ couchup list # Should show no remaining databases!
+
+The same process works for moving from a single 1.x node to a cluster of
+2.x nodes; the only difference is that you must complete cluster setup
+prior to running the couchup commands.
+
+Special Features
+----------------
+
+* Lots of extra help is available via:
+
+.. code-block:: bash
+
+ $ couchup -h
+ $ couchup <sub-command> -h
+
+* Various optional arguments provide for admin login/password,
+ overriding ports, quiet mode and so on.
+
+* ``couchup delete`` will NOT delete your 1.x DBs unless the contents are
+ identical to the replicated 2.x DBs, or you override with the
+ ``-f/--force`` command (be VERY careful with this!!)
+
+* ``couchup replicate`` supports an optional flag, ``-f/--filter-deleted``, to
+ filter delete documents during the replication process. This can
+ improve the performance and disk-size of your database if it has a lot
+ of deleted documents.
+
+ It is IMPORTANT that no documents be deleted
+ from the 1.x database during this process, or those deletions may not
+ successfully replicate to the 2.x database. (It's recommended that
+ you not access or modify the 1.x database at all during the whole
+ ``couchup`` process.)
+
+Manual CouchDB 1.x migration
+============================
+
+If you cannot use the ``couchup`` utility, or prefer to migrate
+yourself, a manual migration is also possible. In this process, a
+full-featured HTTP client such as ``curl`` is required.
+
+The process is similar to the automated approach:
+
+1. Copy all of your 1.x .couch files to the CouchDB 2.x ``data/``
+ directory and start CouchDB (2.x).
+2. Set up replication for each database from the node-local port
+ (default: 5986) to the clustered port (default: 5984). This can be
+ done via the :ref:`/_replicate <api/server/replicate>` endpoint or
+ the :ref:`replicator database <replicator>`.
+3. Rebuild each view by accessing it through the clustered port.
+4. Confirm that all databases and views can be accessed as desired.
+5. Remove the 1.x databases via a ``DELETE`` request on the
+ **node-local** port (default: 5984).
diff --git a/src/install/windows.rst b/src/install/windows.rst
index b5ab0b1..fe9f33f 100644
--- a/src/install/windows.rst
+++ b/src/install/windows.rst
@@ -40,7 +40,8 @@ This is the simplest way to go.
#. `Open up Fauxton`_ (if you hadn't selected autostart CouchDB after
installation, you have to start it first manually)
-#. It's time to Relax!
+#. It's time to Relax! **Be sure to complete the** :ref:`First-time Setup
+ <install/setup>` **steps for a single node or clustered installation.**
.. note::
In some cases you might been asked to reboot Windows to complete
--
To stop receiving notification emails like this one, please contact
['"commits@couchdb.apache.org" <co...@couchdb.apache.org>'].