1.6. Installation via Snap

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

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