If you are an administrator looking for an automated way to deploy Couchbase at scale, look no further – Chef is a great platform solution. Once setup, it is a very clean solution that can work across any number of physical, virtual, or cloud servers, no matter what the size of the infrastructure. Chef enables you to script your infrastructure deployment using code so that you can automate your provisioning and deployment process without much effort. 

In this blog, we will go over the chef recipes used to install couchbase, setup a cluster of couchbase nodes, add some buckets and finally add xdcr replication between clusters.

Before you start – Make sure you are familiar with the basics of chef server, cookbooks and chef-clients. Chef has a huge stack of templates, recipes, knife plugins which can be very useful to maintain large scale setups. http://wiki.opscode.com has good examples and information on this.

Setup a chef-server, workstation and have some nodes added on as chef-clients. Once the above 3 are setup, you are ready to write your Couchbase Cookbook. A forked version of the opscode cookbook is here https://github.com/ketakigangal/couchbase

Install the following cookbooks before downloading the couchbase cookbook – yum, apt-get, windows, build-essential

Get the Couchbase cookbook
git clone  https://github.com/ketakigangal/couchbase

A quick look into the cookbook resources and available customizations
Based on your system needs, you can add more flexible attributes, resources, templates for the nodes and clusters. Ideally use the data-bags to define your cluster naming, here I have used role to describe very simple implementation of two clusters – “west_cluster” and “east_cluster”, more details ahead.

The server.rb and client.rb have the default settings for server and clients. Make sure to reflect the needful couchbase versions, username/password for the server.rb in attributes. For example, the following installs a server 2.0.1-community edition –

default['couchbase']['server']['edition'] = “community”

default['couchbase']['server']['version'] = “2.0.1”

default['couchbase']['server']['username'] = “Administrator”

default['couchbase']['server']['password'] = “password”


The server.rb and client.rb contain the logic for installing and setting up the Couchbase-Server and Clients respectively. Additionally the test_buckets.rb has sample code to create buckets and play around with the bucket settings.

The setup_cluster.rb can be used to setup a cluster, note this requires a role “west_cluster” ( say) to be assigned to each of the nodes of the cluster. Prerequisite to running this is to make sure each of the nodes have a couchbase server installed and started.

Similarly setup_xdcr.rb recipe is used to setup xdcr between two clusters. Prerequisite to using this is you already have 2 couchbase clusters setup  with roles “east_cluster” and “west_cluster”.

* Note : For this script to run, you must have nodes assigned with roles “east_cluster”, “west_cluster” for two separate clusters.


The resources and providers are defined at a node, cluster, bucket level in this directory.

Upload the Cookbook using –

knife cookbook upload couchbase

Add recipes and roles to the node run_list using –

knife node run_list add fqdn-your-node-name “recipe[couchbase::server]”

knife node run_list add fqdn-your-node-name “recipe[couchbase::setup_cluster]”

knife node run_list add fqdn-your-node-name “recipe[couchbase::test_buckets]”

knife node run_list add role fqdn-your-node-name 'role[west_cluster]'

The above will add server, setup_cluster, test_bucket recipes for execution ( in that order) on the chef-client node. Here, we've assigned a role “west_cluster” to nodes to form a west_cluster.

knife show node fqdn-your-node-name






Once you have uploaded the cookbook to the chef-server, you can use the chef-client to execute the cookbook/recipes.


From the chef-client,

   sudo chef-client ( you can used -l debug for debug level log information).  

As output, you will see a similar message like below – 

* couchbase_bucket[modified % modification] action create[2013-07-08T22:57:49-07:00] INFO: Processing couchbase_bucket[modified % modification] action create (couchbase::test_buckets line 77)

[2013-07-08T22:57:49-07:00] INFO: couchbase_bucket[modified % modification] memory_quota_mb changed to 500

[2013-07-08T22:57:49-07:00] INFO: Chef Run complete in 187.264660646 seconds

[2013-07-08T22:57:49-07:00] INFO: Running report handlers

[2013-07-08T22:57:49-07:00] INFO: Report handlers complete

And you are ready to go! 

Steps for running recipe “setup_xdcr.rb”

knife role list



knife node edit fqdn-your-node-name




likewise for the west_cluster.

knife search node “role:west_cluster” -i

2 items found



Setup xdcr by adding the “setup_xdcr” recipe to the source cluster, say “east_cluster”

knife node edit fqdn-your-node-name



This will create a xdcr remote cluster reference and start the replication  from the “east_cluster” to the “west_cluster”

For large scale clusters, use of data-bags is ideal to define and maintain clusters. Likewise maintaining templates for cluster operations, resource creation will be useful in the initial setup. Enjoy!


Posted by Ketaki Gangal

Ketaki Gangal is a Solution Architect at Couchbase. She has experience in technologies like Python, NoSQL, SDKs, Docker, Splunk, Nagios, Kubernetes, AWS.


  1. Hey Ketaki,

    I\’m the maintainer of the \”couchbase\” cookbook. I\’d love to either a) have you integrate the changes from your fork back into it, or b) give maintainer access to CouchBase. Would you be so kind as to get in touch?

    – Julian (jdunn@opscode.com)

    1. Hi Julian,

      Sure, will sync up with you offline on this.

      – Ketaki

  2. Can i see what your role file looks like?

  3. Hi,

    I\’m having trouble with the setup_cluster.rb recipe – is there anyway to get it to take the clustername from the override attributes? It seems to set the cluster name from the name of the role, which means I cannot use a FQDN, which makes it hard to get the nodes to join without using local hosts files etc.

    cluster_name override attribute seems to be ignored: I\’ve tried the following overrides:


    (where default.fqdn.local and override.fqdn.local correctly resolve)

    Password overrides work fine, but cluster_name seems to be ignored :-(

    Any help would be appreciated.


    1. Hi Alan, just curious, were you able to resolve this issue of setting cluster_name via an override attribute?

      1. Hi Terry – sorry no, I wasnt, I\’m actually manually clustering up post-deployment.

        1. the cluster_name is hardcoded into the setup_cluster.rb

          #cluster_name = node[\”cluster_name\”]

          cluster_name = \”west_cluster\”

Leave a reply