{"id":14987908,"url":"https://github.com/apache/couchdb-pkg","last_synced_at":"2025-04-09T20:04:42.481Z","repository":{"id":19524526,"uuid":"87245701","full_name":"apache/couchdb-pkg","owner":"apache","description":"Apache CouchDB Packaging support files","archived":false,"fork":false,"pushed_at":"2025-03-31T11:18:21.000Z","size":25996,"stargazers_count":29,"open_issues_count":8,"forks_count":33,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-04-09T20:04:35.951Z","etag":null,"topics":["apache","big-data","cloud","couchdb","cplusplus","database","erlang","http","javascript","network-client","network-server"],"latest_commit_sha":null,"homepage":"https://github.com/apache/couchdb-pkg","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README-SNAP.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-04T23:46:10.000Z","updated_at":"2025-03-31T11:18:20.000Z","dependencies_parsed_at":"2023-11-19T15:40:37.867Z","dependency_job_id":"6bccce92-6cdf-44a6-a58c-00b475fae9bf","html_url":"https://github.com/apache/couchdb-pkg","commit_stats":{"total_commits":182,"total_committers":23,"mean_commits":7.913043478260869,"dds":0.6538461538461539,"last_synced_commit":"7b466e0163b987f09c6a767d3b0912f1cec0947f"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-pkg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-pkg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-pkg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcouchdb-pkg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/couchdb-pkg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103868,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache","big-data","cloud","couchdb","cplusplus","database","erlang","http","javascript","network-client","network-server"],"created_at":"2024-09-24T14:15:41.172Z","updated_at":"2025-04-09T20:04:42.455Z","avatar_url":"https://github.com/apache.png","language":"Shell","readme":"# CouchDB \"in a snap\"\n\n# Table of Contents\n1. [Installation](#installation)\n1. [Configuration](#configuration)\n1. [Clustering](#clustering)\n1. [Building](#building)\n\n-----\n\n# Installation \u003ca name=\"installation\"\u003e\u003c/a\u003e\n\n## Downloading from the snap store\n\nThe snap can be installed from a file or directly from the snap store:\n\n```bash\n$ sudo snap install couchdb\n```  \n\nIf you are installing on ChromeOS you will need to install `snapd`, and its prerequisites, first.\n\n```bash\nsudo apt install libsquashfuse0 squashfuse fuse\nsudo apt install snapd\n```\n\nIf this is your first time installing couchdb then you will need to set an admin password,\na (random) cookie, and manually start CouchDB.\n\n```bash\n$ sudo snap set couchdb admin=[your-password-goes-here] setcookie=[your-cookie-goes-here]\n$ sudo snap start couchdb \n```\n\n## Enable snap permissions\n\nThe snap installation uses AppArmor to protect your system. CouchDB requests access to \nmount-observe, which is used by the disk compactor to know when to initiate a\ncleanup.\n\nTo connect the interface type:\n\n```bash\n$ sudo snap connect couchdb:mount-observe\n```\n\n# Configuration \u003ca name=\"configuration\"\u003e\u003c/a\u003e\n\nBe sure to read the [CouchDB documentation](http://docs.couchdb.org/en/stable/) first.\n\nSnaps enforce -- what was previous merely suggested -- the Unix philosophy that local \nbinaries or libraries sit in `/usr/local/...` and anything variable is stored separately\nin `/var/local/...`. With this in mind, if are you going to use snaps for your database, \nthe files will be stored in `/var/snap/couchdb/common` and your `/var` partition will need\nto be large enough for your database size. \n\nCouchDB's defaults are stored **read-only** in `/snap/couchdb/current/etc/`.\nThis includes `default.ini` and any `default.d/*` files added in the snap build process.\nThese are all read-only and should never be changed.\n\nUser-configurable files are stored in `/var/snap/couchdb/current/etc/` and are writeable.\nChanges may be made to `local.ini` or placed in any `local.d/*.ini` file. Configuration\nmanagement tools (like puppet, chef, ansible, and salt) can be used to manage these files.\n\nErlang's settings are stored in the `/var/snap/couchdb/current/etc/vm.args` file.  The snap\nconfiguration tool can be used to quickly change the node name and security cookie:\n\n```bash\n$ sudo snap set couchdb name=couchdb@1.2.3.4 setcookie=$COOKIE\n```\n\nWhere COOKIE is an environment variable. You can auto generated a cookie with the command \nbelow. \n\n```bash\n$ export COOKIE=`echo $(dd if=/dev/random bs=1 count=38 status=none | base64 | tr -cd '[:alnum:]')`\n\nBe sure to read `vm.args` to understand what these settings do before changing them.\n\n*Any configuration file changes require restarting CouchDB before they are effective:*\n\n```bash\n$ sudo snap restart couchdb\n```\n\n## Monitoring CouchDB \n\nThe logs, by default, are captured by journald. View the logs with either command:\n\n```bash\n$ snap logs couchdb -f\n$ journalctl -u snap.couchdb* -f\n```\n\n## Removing CouchDB\n\nThere are several difference between installation via 'apt' and 'snap'. One important \ndifference is when removing couchdb. When calling 'apt remove couchdb', the binaries \nare removed but the configuration and the couch database files remain, leaving the \nuser to clean up any databases latter. \n\nCalling 'snap remove couchdb' *will* remove binaries, configurations and the database.\n\nOn newer versions of `snapd` (snapd 2.39+) a snapshot is made of the SNAP_DATA \nand SNAP_COMMON directories and this is stored (subject to disc space) for about 30 days. \nOn these newer version a 'snap remove' followed by a 'snap install' may restore the \ndatabase; but you are best to make your own backup before removing couchdb.\nIf you do not want to keep the configuration or database files you can delete the \nsnapshot by calling snap remove with the --purge parameter. \n\nTo remove your installation either:\n\n```bash\n$ sudo snap remove couchdb\n$ sudo snap remove couchdb --purge\n```\n\n-----\n\n# Clustering \u003ca name=\"clustering\"\u003e\u003c/a\u003e\n\nYou can set up a snap-based cluster on your desktop in no time using the couchdb snap.\n\nIn the example below, we are going to set up a three node CouchDB cluster. (Three is the\nminimum number needed to support clustering features.) We'll also set up a separate,\nsingle machine for making backups. In this example we will be using parallel instance of \nsnaps that is available from version 2.36.\n\nFirst we need to enable parallel instances of snap.\n```bash\n$ snap set system experimental.parallel-instances=true\n```\nWe install couchdb via snap from the store and enable interfaces, open up the bind address\nand set an admin password.\n```bash\n$\u003e snap install couchdb_1\n$\u003e snap connect couchdb_1:mount-observe\n$\u003e snap set couchdb_1 name=couchdb1@127.0.0.1 setcookie=$COOKIE port=5981 admin=$PASSWD\n```\nYou will need to edit the local configuration file to manually set the data directories. \nYou can find the local.ini at ```/var/snap/couchdb_1/current/etc/local.ini``` ensure\nthat the ```[couchdb]``` stanza should look like this\n```\n[couchdb]\n;max_document_size = 4294967296 ; bytes\n;os_process_timeout = 5000\ndatabase_dir = /var/snap/couchdb_1/common/data\nview_index_dir = /var/snap/couchdb_1/common/data\n```\nStart your engine(s) ... \n```bash\n$\u003e snap start couchdb_1\n```\n... and confirm that couchdb is running\n```bash\n$\u003e curl -X GET http://localhost:5981\n```\nThen repeat for couchdb_2 and couchdb_3, editing the local.ini and changing\nthe name, port number for each. They should all have the same admin password and cookie. \n```bash\n$\u003e snap install couchdb_2\n$\u003e snap connect couchdb_2:mount-observe\n$\u003e snap set couchdb_2 name=couchdb2@127.0.0.1 setcookie=$COOKIE port=5982 admin=$PASSWD\n$\u003e snap install couchdb_3\n$\u003e snap connect couchdb_3:mount-observe\n$\u003e snap set couchdb_3 name=couchdb3@127.0.0.1 setcookie=$COOKIE port=5983 admin=$PASSWD\n```\n\n## Enable CouchDB Cluster (using the http interface)\n\nHave the first node generate two uuids (which couchdb can generate for you).\n```bash\n$\u003e curl http://localhost:5981/_uuids?count=2\n```\n\nThese can also be set by batch script.\n\n```bash\n$\u003e export UUID=`curl \"http://localhost:5984/_uuids\" | jq .uuids[0]`\n$\u003e export SECRET=`curl \"http://localhost:5984/_uuids\" | jq .uuids[0]`\n```\n\nEach instance within a cluster needs to share the same uuid ... \n\n```bash\ncurl -X PUT http://admin:$PASSWD@127.0.0.1:5981/_node/_local/_config/couchdb/uuid -d '$UUID'\ncurl -X PUT http://admin:$PASSWD@127.0.0.1:5982/_node/_local/_config/couchdb/uuid -d '$UUID'\ncurl -X PUT http://admin:$PASSWD@127.0.0.1:5983/_node/_local/_config/couchdb/uuid -d '$UUID'\n```\n... and a (different) but common secret ...\n\n```bash\ncurl -X PUT http://admin:$PASSWD@127.0.0.1:5981/_node/_local/_config/couch_httpd_auth/secret -d '$SECRET'\ncurl -X PUT http://admin:$PASSWD@127.0.0.1:5982/_node/_local/_config/couch_httpd_auth/secret -d '$SECRET'\ncurl -X PUT http://admin:$PASSWD@127.0.0.1:5983/_node/_local/_config/couch_httpd_auth/secret -d '$SECRET'\n```\n... after which they can be enabled for clustering\n```bash\ncurl -X POST -H \"Content-Type: application/json\" http://admin:$PASSWD@127.0.0.1:5981/_cluster_setup -d '{\"action\": \"enable_cluster\", \"bind_address\":\"0.0.0.0\", \"username\": \"admin\", \"password\":\"$PASSWD\", \"node_count\":\"3\"}'\ncurl -X POST -H \"Content-Type: application/json\" http://admin:$PASSWD@127.0.0.1:5982/_cluster_setup -d '{\"action\": \"enable_cluster\", \"bind_address\":\"0.0.0.0\", \"username\": \"admin\", \"password\":\"$PASSWD\", \"node_count\":\"3\"}'\ncurl -X POST -H \"Content-Type: application/json\" http://admin:$PASSWD@127.0.0.1:5983/_cluster_setup -d '{\"action\": \"enable_cluster\", \"bind_address\":\"0.0.0.0\", \"username\": \"admin\", \"password\":\"$PASSWD\", \"node_count\":\"3\"}'\n```\nYou can check the status here.\n```bash\ncurl http://admin:$PASSWD@127.0.0.1:5981/_cluster_setup\ncurl http://admin:$PASSWD@127.0.0.1:5982/_cluster_setup\ncurl http://admin:$PASSWD@127.0.0.1:5983/_cluster_setup\n```\n\n## Configure CouchDB Cluster (using the http interface)\nNext we want to join the three nodes together. We do this through requests to the first node.\n```bash\ncurl -X PUT \"http://admin:$PASSWD@127.0.0.1:5981/_node/_local/_nodes/couchdb2@127.0.0.1\" -d '{\"port\":5982}'\ncurl -X PUT \"http://admin:$PASSWD@127.0.0.1:5981/_node/_local/_nodes/couchdb3@127.0.0.1\" -d '{\"port\":5983}'\n\ncurl -X POST -H \"Content-Type: application/json\" http://admin:$PASSWD@127.0.0.1:5981/_cluster_setup -d '{\"action\": \"finish_cluster\"}'\n\ncurl http://admin:$PASSWD@127.0.0.1:5981/_cluster_setup\n```\nIf everthing as been successful, then the three notes can be seen here.\n```bash\n$\u003e curl -X GET \"http://admin:$PASSWD@127.0.0.1:5981/_membership\"\n```\nNow we have a functioning three node cluster. Next we will test it. \n\n## An Example Database\nLet's create an example database ...\n```bash\n$ curl -X PUT http://admin:$PASSWD@localhost:5981/example\n$ curl -X PUT http://admin:$PASSWD@localhost:5981/example/aaa -d '{\"test\":1}' -H \"Content-Type: application/json\"\n$ curl -X PUT http://admin:$PASSWD@localhost:5981/example/aab -d '{\"test\":2}' -H \"Content-Type: application/json\"\n$ curl -X PUT http://admin:$PASSWD@localhost:5981/example/aac -d '{\"test\":3}' -H \"Content-Type: application/json\"\n```\n... and verify that it is created on all three nodes ...\n```bash\n$ curl -X GET http://localhost:5981/example/_all_docs\n$ curl -X GET http://localhost:5982/example/_all_docs\n$ curl -X GET http://localhost:5983/example/_all_docs\n```\n... and is separated into shards on the disk.\n```bash\n  $ ls /var/snap/couchdb_?/common/data/shards/\n```\n\n## Backing Up CouchDB\nThe backup machine we will configure as a single instance (`n=1, q=1`). \n```bash\n$\u003e snap install couchdb_bkup\n$\u003e snap connect couchdb_3:mount-observe\n$\u003e snap set couchdb_bkup name=couchdb0@localhost setcookie=$COOKIE port=5980 admin=$PASSWD\n$\u003e curl -X PUT http://admin:$PASSWD@localhost:5980/_node/_local/_config/cluster/n -d '\"1\"'\n$\u003e curl -X PUT http://admin:$PASSWD@localhost:5980/_node/_local/_config/cluster/q -d '\"1\"'\n```\nWe will manually replicate to this from one (can be any one) of the nodes.\n```bash\n$ curl -X POST http://admin:$PASSWD@localhost:5980/_replicate \\\n    -d '{\"source\":\"http://localhost:5981/example\",\"target\":\"example\",\"continuous\":false,\"create_target\":true}' \\\n    -H \"Content-Type: application/json\"\n$ curl -X GET http://admin:$PASSWD@localhost:5980/example/_all_docs\n```\nThe backup database has a single shard and single directory:\n```bash\n  $ ls /var/snap/couchdb_bkup/common/data/shards/\n```\n-----\n\n# Weather Report\n\nTo run the weatherreport, you'll need to pass the configuration directory. The configuration directory\nneeds to contain both the default.ini (which can be blank) and the local.ini. \n\nFor the weatherreport options, call with `--help` to see usage. call with `--list` to see options. \nThe `-d info` is the mininal required log level to see results. \n\n```bash\n  $ /snap/couchdb/current/bin/weatherreport -c /var/snap/couchdb/current/etc/ -d info memory_use\n['couchdb@127.0.0.1'] [info] Process is using 0.4% of available RAM, totalling 68524 KB of real memory.\n```\n\n-----\n\n# Remote Shell into CouchDB\n\nIn the very rare case you need to connect to the couchdb server, a `remsh` script is\nprovided. You need to specify both the name of the server and the cookie, even if\nyou are using the default. \n```bash\n/snap/bin/couchdb.remsh -n couchdb@localhost -c $COOKIE\n```\n\n# Building this snap \u003ca name=\"building\"\u003e\u003c/a\u003e\n\nThe snapcraft tool can be installed from the snap store as such\n\n```bash\nsudo snap install snapcraft --classic\n```\n\nIf you run snapcraft on your base system it will start either a `multipass` or `lxd`\ncontainer and execute the installation within there. \n\nThis can be tedious if errors occur. An alternative is to create your own lxd \ncontainer and run snapcraft in destructive mode (within the LXD container).\n\n```bash\n\u003e lxc launch ubuntu-daily:22.04 cdb\n\u003e lxc shell cdb\n$ snapcraft --destructive-mode --verbosity=debug\n```\n\nOnce the snap has been built, the snap can be installed locally using `--dangerous`:\n\n```bash\nsudo snap install ./couchdb_3.3.3_amd64.snap --dangerous\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcouchdb-pkg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fcouchdb-pkg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcouchdb-pkg/lists"}