A newer version of this documentation is available.

View Latest


    A Couchbase-Server cluster consists of one or more nodes, each of which is a system running an instance of Couchbase Server.

    Nodes and their Creation

    A Couchbase Server node is a physical or virtual machine that hosts a single instance of Couchbase Server. The establishment of the server on the node entails four stages:

    1. Installed. Couchbase Server has been fully installed on the node, but not yet started.

    2. Started. Couchbase Server has been started. Set-up can now be performed, using Couchbase Web Console, the CLI, or the REST API.

    3. Initialized. Optionally, up to three custom paths have been specified on the current node, respectively corresponding to the locations at which the node’s data, indexes, and analytics are to be saved. Note that if this stage is skipped, and initialization therefore not explicitly performed, path-setting may occur during subsequent provisioning.

    4. Provisioned. The username and password for the Full Administrator have been specified. Additionally, services, service memory-quotas, and buckets may have been specified.

    When any variant of stage 4 has been achieved, the node is considered to be provisioned, and thereby, to be a cluster of one server; and re-initialization is not permitted.

    Note that running multiple instances of Couchbase Server on a single node is not supported.

    Paths for Data, Indexes, and Analytics

    The full, default path for each supported platform are shown in the following table:

    Table 1. Default paths for data-files
    Platform Default directory




    C:\Program Files\couchbase\server\var\lib\couchbase\data

    Mac OS X

    ~/Library/Application Support/Couchbase/var/lib/couchbase/data

    Note that once it has been specified, the data-file path location should not be used to store any data other than that allocated by Couchbase Server; since all such additional data will be deleted.

    The data-file path cannot be spontaneously changed on a node that is active within a cluster: therefore, you should apply the correct, permanent data-file path at configuration-time, prior to the node’s addition to the cluster. If a new path is required, the node must be entirely reconfigured.


    A Couchbase cluster consists of one or more systems, each running Couchbase Server. An existing cluster can be incremented with additional nodes. This can be accomplished in either of the following ways:

    • The routine for adding a new node to the existing cluster is executed on the existing cluster.

      An instance of Couchbase Server must have been installed on the available node, and must be at stage 2, 3, or 4: that is, must itself be started and uninitialized; or started and initialized; or started, initialized, and provisioned (which means, itself a cluster of one node). Adding the available node means that:

      • Any custom paths already established on the available node are kept unchanged on the available node. Note that this allows each individual node within a cluster to maintain its data, indexes, and analytics in its own, node-specific location.

      • If the node is at stage 4, all the results of its prior provisioning are deleted. This includes services, memory-quotas, buckets, bucket-data, and Full Administrator username and password.

      • The services and memory-quotas that are currently the default for the cluster can be optionally assigned to the node that is being added. However, an error occurs if the node does not have sufficient memory. services and memory-quotas for the node can be configured to be other than the default. Alternatively, the default itself can be changed, provided that it does not require more of a given resource than is available on every node currently in the cluster.

    • The routine for joining an existing cluster is executed on the new node.

      The available node must be at stage 2 or 3: that is, it must have been started, and may have had its data, index, and analytics paths configured. However, it cannot have been provisioned in any way: if the routine for Joining is executed on a provisioned node, an error is flagged, and the operation fails.

      Note that services can nevertheless be assigned to the new node during the join operation itself. The memory quota for each service defaults to the setting for the existing cluster. An error occurs if the new node does not have sufficient memory.

    Once a cluster has been created, any of the IP addresses of the cluster-nodes can be used to access data and services. Therefore, provided that one node in the cluster is running the Data Service, the IP address of another node - one that is not running the Data Service - can be specified, in order to access the Data Service: the Cluster Manager ensures that all requests are appropriately routed across the cluster.

    Adding Multiple Nodes

    When the routine for adding nodes is used to increment a cluster with multiple nodes simultaneously, the additions should all be executed on a single node of the cluster: this simplifies the reconfiguration process, and so protects against error.

    Rebalance and Failover

    Rebalance is a process of re-distributing data and indexes among available nodes. This process should be run whenever a node is added to or removed from an existing cluster, say, as part of a scheduled or pre-planned maintenance activity. The process can take place while the cluster is running and servicing requests: clients continue to read and write to the existing structure, while the data is being moved between nodes. Once the data-movement has completed, the updated distribution is communicated to all applications and other relevant consumers.

    Failover is the process by which a cluster-node can be removed; either proactively, to support required maintenance, or reactively, in the event of an outage. Two types of failover are supported, which are graceful and hard. Both can be applied manually when needed. Hard can also be applied automatically, by means of prior configuration: in which case it becomes known as automatic failover.

    Node Quantity

    For production purposes, clusters of less than three nodes are not recommended. For information, see About Deploying Clusters with Less than Three Nodes.


    Initial configuration of Couchbase Server allows the node to be referenced by means of a default IP address: You may choose to specify a different IP address, or a hostname. The hostname must be valid, and must ultimately resolve to a valid IP Address.

    If a node is restarted, Couchbase Server continues to use the specified hostname. Note, however, that if the node is failed over or removed, Couchbase Server will no longer use the specified hostname: therefore, in such circumstances, the node must be reconfigured, and the hostname re-specified.

    Node Certificates

    As described in Certificates, Couchbase Server can be protected by means of x.509 certificates; ensuring that only approved users, applications, machines, and endpoints have access to system resources; and that clients can verify the identity of Couchbase Server.

    Certificate installation for a cluster places the chain certificate chain.pem and the private node key pkey.key in the /opt/couchbase/var/lib/couchbase/inbox/ folder, for each cluster-node. If an attempt is made, either by means of adding or joining, to incorporate a new node into the certificate-protected cluster without the new node itself already being appropriately certificate-protected, the attempt fails. Couchbase Web Console provides the following error message, Attention: Prepare join failed. Error applying node certificate. Unable to read certificate chain file /opt/couchbase/var/lib/couchbase/inbox/chain.pem. The file does not exist.

    Therefore, a new node should be appropriately certificate-protected, before any attempt is made to incorporate it into a certificate-protected cluster. See Certificates for an overview of certificates in the context of Couchbase Server. See Configure Server Certificates for information on configuring server certificates, including certificate installation.