[couchdb-documentation] 01/01: Improve admin user requirement warnings, closes #501

[wo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

wohali pushed a commit to branch admin-warning
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 0fe4b9070b67985370cd1b4f497c7082805a551b
Author: Joan Touzet <jo...@atypical.net>
AuthorDate: Tue Apr 28 12:14:16 2020 -0400

    Improve admin user requirement warnings, closes #501
---
 src/install/freebsd.rst   |  4 ++++
 src/install/snap.rst      |  3 ++-
 src/install/unix.rst      | 17 +++++++++++------
 src/install/upgrading.rst |  3 +++
 src/whatsnew/3.0.rst      |  3 ++-
 5 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/src/install/freebsd.rst b/src/install/freebsd.rst
index 3eb3b4f..a037f16 100644
--- a/src/install/freebsd.rst
+++ b/src/install/freebsd.rst
@@ -26,6 +26,10 @@ Installation from ports
 
 This will install CouchDB from the ports collection.
 
+.. note::
+   Be sure to :ref:`create an admin user <config/admins>` before starting
+   CouchDB for the first time!
+
 Start script
 ------------
 
diff --git a/src/install/snap.rst b/src/install/snap.rst
index 0e0e8fd..1276847 100644
--- a/src/install/snap.rst
+++ b/src/install/snap.rst
@@ -21,7 +21,8 @@ Installation via Snap
 Apache CouchDB provides 'convenience binary' Snap builds through the
 Ubuntu snapcraft repository under the name ``couchdb``. Only snaps built
 from official stable CouchDB releases (``2.0``, ``2.1``, etc.) are available
-through this channel.
+through this channel. There are separate snap channels for each major
+release stream, e.g. ``2.x``, ``3.x``, as well as a ``latest`` stream.
 
 After `installing snapd`_, the CouchDB snap can be installed via::
 
diff --git a/src/install/unix.rst b/src/install/unix.rst
index 40e133e..d9e9597 100644
--- a/src/install/unix.rst
+++ b/src/install/unix.rst
@@ -16,6 +16,11 @@
 Installation on Unix-like systems
 =================================
 
+.. warning::
+    CouchDB 3.0+ will not run without an admin user being created first.
+    Be sure to :ref:`create an admin user <config/admins>` before starting
+    CouchDB!
+
 .. _install/unix/binary:
 
 Installation using the Apache CouchDB convenience binary packages
@@ -128,12 +133,8 @@ joined together and configured consistently across all machines; **follow the**
 
     $ sudo yum -y install epel-release && sudo yum -y install couchdb
 
-Once installed, change the password and uncomment the following line in your ``/opt/couchdb/etc/local.ini`` configuration file::
-
-.. code-block:: ini
-
-    [admins]
-    admin = password
+Once installed, :ref:`create an admin user <config/admins>` by hand before
+starting CouchDB, if your installer didn't do this for you already.
 
 You can now start the service.
 
@@ -341,6 +342,10 @@ Update the permissions for your ini files::
 First Run
 =========
 
+.. note::
+    Be sure to :ref:`create an admin user <config/admins>` before trying to
+    start CouchDB!
+
 You can start the CouchDB server by running::
 
     sudo -i -u couchdb /home/couchdb/bin/couchdb
diff --git a/src/install/upgrading.rst b/src/install/upgrading.rst
index 80a9233..b6a5d03 100644
--- a/src/install/upgrading.rst
+++ b/src/install/upgrading.rst
@@ -42,6 +42,9 @@ If you are running a standalone (single) CouchDB node:
    and merge any changes desired into your own local settings file(s).
 #. Stop CouchDB.
 #. Upgrade CouchDB in place.
+#. Be sure to :ref:`create an admin user <config/admins>` if you do not have
+   one. CouchDB 3.0+ **require** an admin user to start (the admin party has
+   ended).
 #. Start CouchDB.
 #. Relax! You're done.
 
diff --git a/src/whatsnew/3.0.rst b/src/whatsnew/3.0.rst
index 6c61132..3b35e03 100644
--- a/src/whatsnew/3.0.rst
+++ b/src/whatsnew/3.0.rst
@@ -62,7 +62,8 @@ Upgrade Notes
   ...and so on. Documentation has been updated to reflect this change.
 
 * :ghissue:`2389`: CouchDB 3.0 now requires a server admin user to be defined at
-  startup, or will print an error message and exit. (The Admin Party is now over.)
+  startup, or will print an error message and exit. If you do not have one, be sure
+  to :ref:`create an admin user <config/admins>`. (The Admin Party is now over.)
 
 .. figure:: ../../images/23379351593_0c480537de_q.jpg
   :align: center