This is an automated email from the ASF dual-hosted git repository. ronny pushed a commit to branch docs/cherry-pick-snap in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit b2c50e4831501c2a91f8fa29809771598193f669 Author: Simon Klassen <[email protected]> AuthorDate: Wed Jan 3 21:55:49 2024 +0800 Re-wrote snap installation guide lines for 3.3 (#4940) Updated installation guide lines for 3.3.3. --------- Co-authored-by: Simon Klassen <[email protected]> Co-authored-by: Ronny Berndt <[email protected]> --- src/docs/src/install/snap.rst | 86 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 16 deletions(-) diff --git a/src/docs/src/install/snap.rst b/src/docs/src/install/snap.rst index 904ce657e..a08f9996d 100644 --- a/src/docs/src/install/snap.rst +++ b/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
