Re-wrote snap installation guide lines for 3.3 (#4940)

Updated installation guide lines for 3.3.3.

---------

Co-authored-by: Simon Klassen <6997477+sklassen@users.noreply.github.com>
Co-authored-by: Ronny Berndt <ronny@apache.org>

src/docs/src/install/snap.rst

@@ -19,29 +19,83 @@ Installation via Snap
 .. highlight:: sh
 
 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. There are separate snap channels for each major
-release stream, e.g. ``2.x``, ``3.x``, as well as a ``latest`` stream.
+Ubuntu snapcraft repository under the name `couchdb snap`_. These are
+available in separate snap channels for each major/minor release stream,
+e.g., ``2.x``, ``3.3``, and a ``latest`` stream.
 
-After `installing snapd`_, the CouchDB snap can be installed via::
+Once you've completed `installing snapd`_, you can install the CouchDB snap via::
 
     $ sudo snap install couchdb
 
-CouchDB will be installed at ``/snap/couchdb``. Data will be stored at
-``/var/snap/couchdb/``.
+After installation, set up an admin password and a cookie using a snap hook.
+Then, restart the snap for changes to take effect::
 
-Please note that all other file system paths are **relative to the snap
-`chroot`** instead of the system root. In addition, the exact path
-depends on your system. For example, when you normally want to
-reference `/opt/couchdb/etc/local.ini`, under snap, this could live at
-`/snap/couchdb/5/opt/couchdb/etc/local.ini`.
+    $ sudo snap set couchdb admin=[your-password] setcookie=[your-cookie]
+    $ sudo snap restart couchdb
 
-**Your installation is not complete. Be sure to complete the**
-:ref:`Setup <setup>` **steps for a single node or clustered installation.**
+CouchDB will be installed (read only) at ``/snap/couchdb/current/``.
+Data files will be written to ``/var/snap/couchdb/common/data``, and
+(writable) configuration files will be stored in ``/var/snap/couchdb/current/etc``.
 
-Further details on the snap build process are available in our
-`couchdb-pkg git repository`_.
+.. note::
 
+    Your installation is not complete. Follow the
+    :ref:`Setup <setup>` steps for a single node or clustered installation.
+
+Snaps use AppArmor and are closely tied to systemd. They enforce that
+only writable files are housed under ``/var/snap``. Ensure that ``/var``
+has sufficient space for your data requirements.
+
+To view logs, access them via ``journalctl snap.couchdb`` or using the ``snap logs``
+command::
+
+    $ sudo snap logs couchdb -f
+
+When installing from a specific channel, snaps are automatically refreshed with
+new revisions. Revert to a previous installation with::
+
+    $ sudo snap revert couchdb
+
+After this, updates will no longer be received. View installed snaps and alternative
+channels using the list and info commands::
+
+    $ snap list
+    $ snap info couchdb
+
+As easily as they are installed, snaps can be removed::
+
+    $ sudo snap remove couchdb
+    $ sudo snap remove couchdb --purge
+
+The first command stops the server, removes couchdb from the list, and the filesystem
+(keeping a backup for about 30 days if space permits). If you reinstall couchdb, it
+tries to restore the backup. The second command removes couchdb and purges any backups.
+
+When troubleshooting couchdb snap, check the logs first. You'll likely need to inspect
+``/var/snap/couchdb/current/etc/local.ini`` to verify the data directory or modify
+admin settings, port, or address bindings. Also, anything related to Erlang runtime
+check ``/var/snap/couchdb/current/etc/vm.args`` to view the erlang name.
+
+The most common issue is couchdb not finding the database files. Ensure that
+``local.ini`` includes the following stanza and points to your data files:
+
+.. code-block:: ini
+
+    [couchdb]
+    ;max_document_size = 4294967296 ; bytes
+    ;os_process_timeout = 5000
+    database_dir = /var/snap/couchdb/common/data
+    view_index_dir = /var/snap/couchdb/common/data
+
+.. note::
+
+    Remember, you cannot modify the ``/snap/couchdb/`` directory, even with sudo,
+    as the filesystem is mounted read-only for security reasons.
+
+For additional details on the snap build process, refer to our
+`couchdb-pkg git repository`_. This includes instructions on setting up a cluster
+using the command line.
+
+.. _couchdb snap: https://snapcraft.io/couchdb
 .. _installing snapd: https://snapcraft.io/docs/core/install
 .. _couchdb-pkg git repository: https://github.com/apache/couchdb-pkg