Installing multiple instances

Installing multiple instances

Multiple instances of Couchbase Server can be installed on one physical machine for the LInux operating system. The number of instances depends on the capacity of the physical machine.

Attention: Multiple instances on one machine are allowed only for development purposes.


Make sure that a minumum of 4Gb RAM and 8 Core CPU are available for each Couchbase Server instance. When installing multiple instances on a physical machine, install as one of these two users:
  • sudo user
  • non-root, non-sudo user
Note: Refer to the lists of the reserved Couchbase Server network ports and user-defined ports before creating any new user-defined ports.


Install each cluster instance on a different physical machine to provide for data recovery if a failure occurs.
Note: The number of Couchbase Servers that can be installed on a physical machine depends on the available RAM and CPU capacities.

The following graphic shows a cluster configuration with multiple Couchbase instances on a physical machine. In addition, by having three (3) Couchbase Servers in a cluster, each installed on different physical machines, the configuration reduces the risk of data loss from a hardware failure.

Setting up multiple instances

To set up multiple instances running on a physical machine:

  1. Install Couchbase Server as a sudo user or as a non-root, non-sudo user. For more information about installing as non-root, non-sudo, see Installing as non-root, non-sudo
  2. Create user-defined ports in the file /opt/couchbase/etc/couchbase/static_config .
  3. In the /etc/security/limits.conf file, make sure that the hard and soft limits for the nofile parameter are set to a value greater than 10240.
  4. Change the short_name parameter that identifies the instance (default: ns_1), to a different short_name in the /opt/couchbase/etc/couchbase/static_config file.
    • The short_name value must be different for each instance that resides on the same physical server.
  5. Change the two occurrences of short_name in the /opt/couchbase/bin/couchbase-server file. For example, use the sed utility.
    •  sed -i ‘s/ns_1/ns_inst1/g’ bin/couchbase-server
  6. Start the Couchbase Server instance.
  7. Repeat the steps to install other instances.
Important: While creating a cluster, make sure that the perServer RAM quota is calculated looking at the number of instances to be installed on that machine. When configuring a cluster instance, Couchbase Server provides a default value for the perServer RAM quota. This default value is based on the total RAM quota available on the physical machine. Modify this value as needed.


If any bucket created on the nodes appear to be in a pending state, or if rebalance fails with an error
there could be a mismatch of the short_name value in the following files:



  • Cbrecovery is unavailable on customized ports.
  • Cbworkloadgen is unavailable.
  • Offline upgrade is unavailable.
  • If a bucket is created on a dedicated port, some of the operations can result in the error could not listen on port xxx , even though the operation still succeeds. This error is logged regardless of the port that is used.