A newer version of this documentation is available.

View Latest

Initialize a Node

      A new Couchbase Server node can be initialized, to establish node-specific paths for local storage.

      Understanding Initialization

      Following installation and start-up of Couchbase Server, a node must be:

      • Initialized, whereby its disk-paths for data, indexes, analytics, and eventing can be established.

      • Provisioned, whereby all other details, including Full Administrator credentials, service assignments, and memory quota-definitions are established.

      Optionally, initialization can be performed explicitly and independently of provisioning, as a prior process, in order to establish custom disk-paths. When the node is subsequently provisioned, these are preserved (unless, as is possible with UI-based provisioning, they are optionally overwritten, and the node is thus re-initialized).

      If initialization is not explicitly performed, it will occur as part of the eventual provisioning process, and default disk-path values will be applied.

      Note that disk-paths cannot be changed after a node has been provisioned, and has thus either become a cluster of one node, or has been added to a cluster of other nodes.

      Note also that initialization allows a node to be named. Before assigning a name to the node, read the information provided in Naming Clusters and Nodes.

      Examples on This Page

      The examples in the subsections below show how to initialize the same node; using the CLI, and the REST API respectively.

      The examples assume:

      • Couchbase Server has been installed and started.

      • The IP address of the node is

      Using the UI to Initialize

      UI-based initialization can only be performed as part of the overall provisioning process. This is described in Create a Cluster.

      Note that in Couchbase Server Version 7.0.2 and later, UI-based initialization provides additional options for establishing the address family for the cluster: if you wish to restrict (rather than merely require) your cluster to use either IPv4 or IPv6, initialize by means of the UI, as described in Create a Cluster.

      The instructions provided below for CLI and REST allow you to require either IPv4 or IPv6 as the address family for the cluster: thus, if connectivity by means of the selected address family is not available for some reason, the cluster and its services do not start; and corrective action can be taken. Once connectivity is established with the required address family, communications by means of the other address family are still permitted.

      Information on managing address families for the cluster after the cluster has been established are provided in Manage Address Families.

      Initialize a Node with the CLI

      To initialize a node with the CLI, use the node-init command, as follows:

      /opt/couchbase/bin/couchbase-cli node-init -c \
      -u placeholdername -p placeholderpwd \
      --node-init-data-path /opt/couchbase/var/lib/couchbase/data \
      --node-init-index-path /opt/couchbase/var/lib/couchbase/data \
      --node-init-eventing-path /opt/couchbase/var/lib/couchbase/data \
      --node-init-analytics-path /opt/couchbase/var/lib/couchbase/data \
      --node-init-java-home /opt/couchbase/bin/java \
      --node-init-hostname node1-devcluster.com \

      This initializes the disk-paths for data, indexes, eventing, and analytics on node to the values shown. Note that the command requires that a username and password be specified, although the node has not yet been provisioned with credentials. Placeholders are therefore provided: these can be overwritten during subsequent provisioning. The command specifies IPv4 as the address family for the node, and assigns the node a hostname of node1-devcluster.com. (To specify IPv6, use the --ipv6 flag instead.) The command also specifies an administrator-created folder, /opt/couchbase/bin/java, as the path for an alternative Java Runtime Environment (JRE), already installed on the current node, to be used for the Analytics Service.

      If successful, the operation returns the following:

      SUCCESS: Node initialized

      For more information, see the reference for the node-init command.

      Initialize a Node with the REST API

      To initialize a node with the REST API, use the POST /nodes/self/controller/settings http method and URI, as follows:

      curl  -u Administrator:password -v -X POST \ \
        -d 'data_path=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fdata&' \
        -d 'index_path=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fidata&' \
        -d 'cbas_path=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fadata&' \
        -d 'eventing_path=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fedata&' \
        -d 'java_home=%2Fopt%2Fcouchbase%2Fbin%2Fjava'

      This initializes the disk-paths for data, indexes, analytics, and eventing on node to the values shown.

      For more information on /nodes/self/controller/settings, see Creating a New Cluster.

      Note that to assign a name to the node, the POST /node/controller/rename http method and URI can be used, as follows:

      curl -v -X POST -u Administrator:password \ \
      -d hostname=node1-devcluster.com

      The assigns the name node1-devcluster.com to the node.

      Next Steps

      Following initialization, a node can be provisioned so as to become a Couchbase Cluster of one node. See Create a Cluster for details.