Improve admin user requirement warnings, closes #501 (#529)
diff --git a/src/install/freebsd.rst b/src/install/freebsd.rst
index 3eb3b4f..8e5cc87 100644
--- a/src/install/freebsd.rst
+++ b/src/install/freebsd.rst
@@ -26,6 +26,10 @@
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 @@
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..4689041 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 @@
$ 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 @@
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..eff3dca 100644
--- a/src/install/upgrading.rst
+++ b/src/install/upgrading.rst
@@ -42,6 +42,9 @@
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..349b7e6 100644
--- a/src/whatsnew/3.0.rst
+++ b/src/whatsnew/3.0.rst
@@ -62,7 +62,8 @@
...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