.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

.. _install/snap:

=====================
Installation via Snap
=====================

.. highlight:: sh

Apache CouchDB provides 'convenience binary' Snap builds through the
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.

Once you've completed `installing snapd`_, you can install the CouchDB snap via::

    $ sudo snap install couchdb

After installation, set up an admin password and a cookie using a snap hook.
Then, restart the snap for changes to take effect::

    $ sudo snap set couchdb admin=[your-password] setcookie=[your-cookie]
    $ sudo snap restart couchdb

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``.

.. 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