Installing Multiple Instances on Linux Platforms

      Multiple instances of Couchbase Server can be installed on one physical machine for the Linux operating system.
      This installation method is intended for development purposes only and not supported in production.

      The number of Couchbase Server instances running on a single machine depends on its physical capacity.


      Make sure that a minimum of 4Gb RAM and 8 Core CPUs 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

      Refer to the lists of the reserved Couchbase Server network ports and user-defined ports before creating any new user-defined ports.
      The number of Couchbase Servers that can be installed on a physical machine depends on the available RAM and CPU capacities.

      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. See Non-Root Install and Upgrade, for instructions on non-root install.

      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.

      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:



      Following are some of the limitations for running multiple instance of Couchbase Server on a single machine:

      • Some of the Couchbase Server tools will be unavailable to run on the customized ports for multiple Couchbase instances:

        • cbrecovery

        • cbworkloadgen

      • Offline upgrade for multiple instances 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.