Setting up a Couchbase CE Cluster


    In this tutorial you can learn how to set up a Couchbase Server cluster, how to manage services availability, and replicate data.

    This tutorial was built using the Community Edition(CE) of Couchbase Server, so you can use this distribution to follow this guide free of charge.


    To set up a cluster, you need to install Couchbase Server on multiple nodes. In this section you can find instructions on how to do so, please follow these instructions to deploy 3 nodes. Later on, we will refer to those as node-1, node-2 and node-3.

    Tested for Ubuntu 18.04, macOS Mojave and Windows 10.

    You can install the server in a machine (bare metal) or use a containerization tool such as Docker, to speed up this part of the tutorial.


    This would be the fastest and easiest way to get the server started. If you need help installing Docker, their official documentation contains install guides for multiple OS.

    After Docker is up and running you can type this command on your terminal to launch the server.

    docker run -itd --name couchbase-server -p 8091-8094:8091-8094 -p 11210:11210 couchbase:community

    For a more extensive install guide, you can check the Couchbase image description on Dockerhub.

    Bare metal

    • Ubuntu 18.04

    • Windows 10

    • macOS

    First, open your terminal and install these tools, used by some of the core Couchbase Server packages.

    sudo apt update
    sudo apt install curl lsb-release gnupg

    Download and install the .deb meta-package, it contains the necessary information for apt to retrieve Couchbase’s necessary packages and public signing keys.

    curl -O
    sudo dpkg -i ./couchbase-server-community_6.5.0-ubuntu18.04_amd64.deb

    Now you are ready to install the Couchbase Server CE latest release.

    sudo apt update
    sudo apt install couchbase-server-community

    For a more extensive install guide, you can follow the Couchbase documentation for Ubuntu 18.04.

    Download the MSI installer from this link.

    Execute it and follow the wizard.

    install windows

    For a more extensive install guide, you can follow the Couchbase documentation for Windows 10.

    Download the zip file from this link and open it, it will be send to Downloads folder.

    mac unzip

    Open the folder and drag the application to you Applications folder.

    mac open

    Double click the Couchbase Server application to start the server.

    mac installed

    You can now use the navigation tab icon on the top right corner of your desktop to manage your server.

    mac bar mac bar open

    For a more extensive install guide, you can follow the Couchbase documentation for macOS.


    Provisioning establishes the full administrator credentials for the server and specifies its service-assignments and memory-quota allocations. When provisioning a node, options are to create a new cluster with a sole member or joining an existing one. You can provision a node by CLI, REST API or Web UI.

    First Node

    The easiest way is with the help of the Web UI, so open your browser and navigate to port 8091 of node-1. You should see something like this now.

    couchbase front

    Since this will be the first node of our 3 nodes cluster, click on Setup New Cluster. Choose a server name and an administrator with a password, these credentials must be saved for later use.

    first part

    The next step is to configure some aspects of your cluster like services available, memory utilization and storage path for your data and indexes. Click on the Configure Disk, Memory, Services button.

    second part

    The default path and memory quotas should be fine for this test cluster. If you want to learn more about couchbase services and how to properly tune your server, follow this link.

    Quick explanation though:

    • Data: Supports the storing, setting, and retrieving of data-items, specified by key.

    • Query: Parses queries specified in the N1QL query language, executes the queries, and returns results. This service interacts with both the Data and Index services.

    • Index: Creates indexes, for use by the Query service.

    • Search: Create indexes specially purposed for Full-Text Search. This supports language-aware searching; allowing users to search for, say, the word beauties, and additionally obtain results for beauty and beautiful.

    Insert Data

    Right now, you have a functional one node cluster, let’s add some data before adding more nodes. If you look close enough, there is a note indicating you to add a sample bucket. Click it and choose any of the options, you will see a notification for the task. When it finishes you can explore your new sample data on the Buckets tab.

    insert sample

    On the Servers tab, you can find a list of your nodes, and how much data is currently stored. If you look closer, there is also a warning telling you that you need at least one more node to be able to replicate your data.


    Join Another Node

    Open up your browser again, this time open the Web UI of node-2 and press on Join Existing Cluster. Enter node-1 address and credentials. At the bottom, press the arrow to configure some aspect of this node. You could probably notice there are fewer options than those available for node-1, that’s because you will form part of a previously created cluster, so most configurations will be imported.

    join 2

    In the Dashboard tab you can find information about your cluster. To get a more detailed view, go to the Server tab.

    Right now your new node is waiting for a rebalance operation to start serving data or holding replicas. To manually force such operation, press on the Rebalance button.


    That may take a while, so be patient, when it’s over, each document and its replica will be distributed between your nodes. As a quick indicator, bellow the items column, there is information about how many documents/replicas are currently being stored on each node.

    Join(Add) the Last Node

    Adding another node or more can be done easily by just following the steps in the section above as many times as necessary. Enter the Web UI from node-3 now, and follow those steps again.

    With each node added, documents and replicas get more and more sparsely between your cluster. This is quite good, you can access all your data from any node and replicas will be available if any node crashes or gets removed.

    show replica

    The number of replicas per document can be changed for any bucket, increasing that factor will make your cluster more secure against crashes in exchange for disk capacity. To change the replica level click the bucket on the Buckets tab, and then press the Edit button. The desired value is under Advanced bucket settings.

    replica change

    Remove a Node

    Couchbase Server nodes can indistinctly be removed or added, there are no special nodes with services or processes that can’t be replaced on the run. Let’s test that by removing the very first node we provisioned.

    remove first

    After a rebalance operation, your cluster will drop all documents and replicas from node-1 and form a 2 nodes cluster again with all data.

    Next Steps

    We recommend you to follow our next tutorials, go to the Getting Started with Couchbase Community Edition page to find the full list.

    Also, you could review Couchbase Documentation to learn more about all sorts of topics.