dch commented on code in PR #4955:
URL: https://github.com/apache/couchdb/pull/4955#discussion_r1447764409
##########
src/docs/src/install/freebsd.rst:
##########
@@ -16,71 +16,93 @@
Installation on FreeBSD
=======================
-Installation from ports
-=======================
+Installation
+============
-.. code-block:: text
+Use `the pre-built binary packages`_ to install CouchDB::
- cd /usr/ports/databases/couchdb
- make install clean
+ pkg install couchdb3
-This will install CouchDB from the ports collection.
+Alternatively, it is possible installing CouchDB from the Ports
+Collection::
+
+ cd /usr/ports/databases/couchdb3
+ make install clean
.. note::
Be sure to :ref:`create an admin user<config/admins>` before starting
CouchDB for the first time!
-Start script
-------------
+Service Configuration
+=====================
-The following options for ``/etc/rc.conf`` or ``/etc/rc.conf.local`` are
-supported by the start script (defaults shown)::
+The port is shipped with a script that integrates CouchDB with
+FreeBSD's `rc.d service framework`_. The following options for
+``/etc/rc.conf`` or ``/etc/rc.conf.local`` are supported (defaults
+shown)::
- couchdb_enable="NO"
- couchdb_enablelogs="YES"
- couchdb_user="couchdb"
+ couchdb3_enable="NO"
+ couchdb3_user="couchdb"
+ couchdb3_erl_flags="-couch_ini /usr/local/libexec/couchdb3/etc/default.ini
/usr/local/etc/couchdb3/local.ini"
+ couchdb3_chdir="/var/db/couchdb3"
-After enabling the couchdb rc service use the following command to start
CouchDB::
+After enabling the ``couchdb3`` service (by setting
+``couchdb3_enable`` to ``"YES"``), use the following command to start
+CouchDB::
- /usr/local/etc/rc.d/couchdb start
+ service couchdb3 start
-This script responds to the arguments `start`, `stop`, `status`, `rcvar` etc..
+This script responds to the arguments `start`, `stop`, `status`,
+`rcvar` etc. If the service is not yet enabled in ``rc.conf``, use
+``onestart`` to start it up ad-hoc.
-The start script will also use settings from the following config files:
+The service will also use settings from the following config files:
-- /usr/local/etc/couchdb/default.ini
-- /usr/local/etc/couchdb/local.ini
+- ``/usr/local/libexec/couchdb3/etc/default.ini``
+- ``/usr/local/etc/couchdb3/local.ini``
-Administrators should use ``default.ini`` as reference and only modify the
-``local.ini`` file.
+Administrators should use ``default.ini`` as a reference and only
+modify the ``local.ini`` file.
Post install
-------------
-**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:
+**The installation is not complete. Be sure to complete the**
+:ref:`Setup <setup>` **steps for a single node or clustered
+installation.**
-I used the ``pw`` command to add a user "couchdb" in group "couchdb":
+Also note that the port will probably show some messages after the
+installation happened. Make note of these instructions, although they
+can be found `in the ports tree`_ for later reference.
-.. code-block:: text
+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.
- pw user add couchdb
- pw user mod couchdb -c 'CouchDB, time to relax' -s /usr/sbin/nologin -d
/var/lib/couchdb
- pw group add couchdb
+Use the ``pw`` command from the base system to add a user ``couchdb``
+in group ``couchdb``::
-The user is added to ``/etc/passwd`` and should look similar to the following:
+ # pw useradd couchdb
+ # pw usermod couchdb -c 'CouchDB Account' -s /usr/sbin/nologin -d
/var/empty
+ # pw groupadd couchdb
+ # pw groupmod couchdb -m couchdb
-.. code-block:: text
+Then the user is added to ``/etc/passwd`` and the group to
+``/etc/groups``. These could be verified in the following way::
- shell# grep couchdb /etc/passwd
- couchdb:*:1013:1013:Couchdb, time to
relax:/var/lib/couchdb/:/usr/sbin/nologin
+ $ grep couchdb /etc/passwd
+ couchdb:*:1013:1013:CouchDB Account:/var/empty:/usr/sbin/nologin
+ $ grep couchdb /etc/groups
+ couchdb:*:1013:couchdb
-To change any of these settings, please refrain from editing `/etc/passwd` and
-instead use ``pw user mod ...`` or ``vipw``. Make sure that the user has no
-shell, but instead uses ``/usr/sbin/nologin``. The '*' in the second field
means
-that this user can not login via password authorization. For details use
+To change any of these settings, please refrain from editing
+``/etc/passwd`` and instead use ``pw usermod ...`` or ``vipw``. Make
+sure that the user has no shell, but instead uses
+``/usr/sbin/nologin``. The ``*`` in the second field means that this
+user can not login via password authorization. For the details, see
`man 5 passwd`_.
-.. _man 5 passwd: http://linux.die.net/man/5/passwd
+.. _the pre-built binary packages:
https://docs.freebsd.org/en/books/handbook/ports/
+.. _rc.d service framework:
https://man.freebsd.org/cgi/man.cgi?query=service&apropos=0&sektion=0&manpath=default&arch=default&format=html
+.. _in the ports tree:
https://github.com/freebsd/freebsd-ports/blob/main/databases/couchdb3/files/pkg-message.in
+.. _man 5 passwd:
https://man.freebsd.org/cgi/man.cgi?query=passwd&apropos=0&sektion=0&manpath=default&arch=default&format=html
Review Comment:
IMHO we can remove all of the passwd/group related stuff, no? Or are there
common circumstances where this will help somebody who uses FreeBSD but doesn't
know about groups & passwords yet?
The ports tree should be the now-canonical
https://cgit.freebsd.org/ports/tree/databases/couchdb3/files/pkg-message.in
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
