Home • Use • Develop • Troubleshoot • API • Changelog

Installing & Using BigCouch

NB: if you want to hack or extend BigCouch, you should use these instructions instead.

Install

Cloudant provides binary packages for selected platforms. The packages bundle the minimum subset of Erlang/OTP R14B01 required to operate BigCouch and specify a Cloudant package of Mozilla SpiderMonkey 1.8.5 as a dependency.

Debian

sudo apt-get install lsb-release
echo "deb http://packages.cloudant.com/debian `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/cloudant.list
sudo apt-get update
sudo apt-get install bigcouch

Ubuntu

echo "deb http://packages.cloudant.com/ubuntu `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/cloudant.list
sudo apt-get update
sudo apt-get install bigcouch

RedHat / CentOS / Amazon Linux

Note: If you are using CentOS 5, you will need to add the EPEL repository to get the dependent spidermonkey library.

cat <<'EOF' > /etc/yum.repos.d/cloudant.repo
[cloudant]
name=Cloudant Repo
baseurl=http://packages.cloudant.com/rpm/$releasever/$basearch
enabled=1
gpgcheck=0
EOF

yum install bigcouch

Use

Configuring your nodes

Each BigCouch node needs a unique erlang host name and the same secret cookie value. Locate the vm.args file in your installation (typically /opt/bigcouch/etc/vm.args) and set the -name property to bigcouch@fqdn where fqdn is the fully-qualified domain name for your node. The fqdn must be resolvable by all nodes in your cluster. Next, either arrange for ~/.erlang.cookie to contain a shared, secret string on all nodes, or add -setcookie secret to vm.args where secret is some secret value of your choosing. Be sure to use the same secret value on all your nodes.

Joining a node to a cluster

Each BigCouch node has a local nodes database, accessible through the backend interface on port 5986. Documents in the nodes DB name nodes in the cluster. To add a new node, create a document with that node's name as the ID. For example

curl -X PUT http://foo.example.com:5986/nodes/bigcouch@bar.example.com -d {}

Everything else should be automatic, provided the machines allow inbound TCP connections to the Erlang Port Mapper daemon on port 4369

Now What?

If the above steps were successful, you should have a running BigCouch cluster that looks just like a standalone CouchDB. You may interact with it the same way you would a standalone CouchDB, via the HTTP REST interface. Because every node can handle requests equally, you may want to put a reverse proxy in front of the cluster and set up a round-robin strategy for distributing incoming requests across all of your cluster's nodes. Cloudant recommends HAProxy. There are a handful of BigCouch-specific extensions to the API that control the sharding topology of new databases and the quorum algorithms for read and write operations. These are documented on the api page.