Re-wrote snap installation guide lines for 3.3 (#4940) (#4941)
Updated installation guide lines for 3.3.3.
---------
Co-authored-by: Simon Klassen <6997477+sklassen@users.noreply.github.com>
diff --git a/src/docs/src/install/snap.rst b/src/docs/src/install/snap.rst
index 904ce65..a08f999 100644
--- a/src/docs/src/install/snap.rst
+++ b/src/docs/src/install/snap.rst
@@ -19,29 +19,83 @@
.. 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
