A newer version of this documentation is available.

View Latest

cluster-init

      +

      Initializes a Couchbase Server cluster

      SYNOPSIS

      couchbase-cli cluster-init [--cluster <url>] [--cluster-username <username>]
          [--cluster-password <password>] [--cluster-port <port>]
          [--cluster-ramsize <mebibytes>] [--cluster-name <name>]
          [--cluster-index-ramsize <mebibytes>] [--cluster-fts-ramsize <mebibytes>]
          [--cluster-eventing-ramsize <mebibytes>]
          [--cluster-analytics-ramsize <mebibytes>]
          [--index-storage-setting <setting>] [--services <services>]
          [--update-notifications <1|0>]

      DESCRIPTION

      Initializes the first node in a Couchbase Server cluster. Before initializing a cluster you need to decide which services you will be running on this node as well as the memory quota for each service you are starting. Services started with cluster-init will be running on this server only. Future servers that are added to this cluster may be configured with different services running on them. Note that the data service is always required on the first node. Memory quotas for each service are global settings and will apply to each node added to the cluster. The memory quota for a service only applies if that service is running on a given server. You may also define the index storage mode which will determine how the global secondary indexes (GSI) are stored.

      OPTIONS

      -c
      --cluster

      Specifies the hostname of the cluster to initialize. By default, this parameter is set to localhost:8091 for this command. See the HOST FORMATS section for more information on specifying a hostname.

      --cluster-username

      When starting a new cluster you need to create the Couchbase Server built-in administrator user for the cluster. This user will be able to access the Couchbase Server Administration Console as well as be used for data access and future configuration. This option specifies the username for the administrator user.

      --cluster-password

      When starting a new cluster you need to create the Couchbase Server built-in administrator user for the cluster. This user will be able to access the Couchbase Server Administration Console as well as be used for data access and future configuration. This option specifies the password for the administrator user.

      --cluster-ramsize

      Specifies the data services memory quota (in MiB). This quota will be assigned to all future nodes added to the cluster with the data service.

      --cluster-fts-ramsize

      Sets the full-text service memory quota (in MiB). This parameter is required if the full-text service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the full-text service.

      --cluster-index-ramsize

      Sets the index service memory quota (in MiB). This parameter is required if the index service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the index service.

      --cluster-eventing-ramsize

      Sets the Eventing service memory quota (in MiB). This parameter is required if the Eventing service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the eventing service.

      --cluster-analytics-ramsize

      Sets the Analytics service memory quota (in MiB). This parameter is required if the Analytics service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the analytics service.

      --cluster-name

      Sets the name for this cluster. Naming clusters is useful when you have multiple Couchbase Server clusters in your deployment.

      --cluster-port

      Specifies the port for the Couchbase Administration Console. Defaults to port 8091.

      --index-storage-setting

      Specifies the index storage mode for the index service. Accepted storage modes are "default" for the standard index backend or memopt for memory optimized indexes. If the index service is specified to be started with the --services command then this parameter defaults to "default". If the index service is not specified to be started then the index storage mode will not be set. You will then be required to set the index storage mode when the first index service is started on a server in the cluster. You may also define the index storage mode even if an index service is not started on the first node and it will be remembered when the first index service is added in the future. You may not change this parameter while there are index nodes in the cluster.

      --services

      Specifies the services to start on this cluster. You may not change the services running on this node once the cluster has been initialized. This options takes a comma separated list of services. Accepted services are "data", "index", "query", "fts", "eventing", "analytics" and "backup" specified as a comma-separated list. This parameter defaults to "data".

      --update-notifications

      Specifies whether or not software update notifications and sharing of system performance information should be enabled. To enable notifications set this flag to "1". To disable notifications set this flag to "0". By default it’s enabled and notifications will be displayed in the Couchbase web console when a new version of Couchbase Server is available. This system also collects information about use and experience with the product every time an administrator interacts with the administrator user interface. It collects configuration, usage and performance data, including cluster information (such as settings and configuration, software version, cluster ID, load levels, and resource quotas), and browser and network information (such as IP address, inferred geolocation only at the city level, and browser type). This does not allow Couchbase to track your specific interactions or usage of Couchbase Server. Couchbase, Inc never accesses or collects any data stored within Couchbase Server. This feature can be disabled at any time by using 'couchbase-cli-setting-notification.' For more information on this feature, please see the “Couchbase Server Privacy FAQ” in the product documentation, which supplements the Couchbase Privacy Policy available online.

      HOST FORMATS

      When specifying a host for the couchbase-cli command the following formats are expected:

      • couchbase://<addr>

      • <addr>:<port>

      • http://<addr>:<port>

      It is recommended to use the couchbase://<addr> format for standard installations. The other two formats allow an option to take a port number which is needed for non-default installations where the admin port has been set up on a port other that 8091.

      EXAMPLES

      To create a Couchbase Server cluster with only the data service on the first node and a memory quota of 4096MiB run the following command.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
       --cluster-password password --services data --cluster-ramsize 4096

      To create a Couchbase Server cluster with the data and index service then you also need to set the memory quotas for each service as well as the index storage mode since you are starting the index service.

      To create a cluster with an index memory quota of 1024MiB, a data service memory quota of 2048MiB and a memory optimized index storage mode run the following command.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
       --cluster-password password --services data,index --cluster-ramsize 2048 \
       --cluster-index-ramsize 1024 --index-storage-setting memopt

      To create a Couchbase Server cluster with all services then you need to set the memory quotas for the Data, Index, Full-Text, Eventing and Analytics service. The quotas are set to 2048MiB, 1024MiB, 1024MiB, 1024MiB and 1024MiB respectively. A quota is not set for the query service since it does not have a memory quota. You also need to set the index storage mode for the index service, which will be set to "default" since the service is started on the first node.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
       --cluster-password password --services data,index,query,fts,analytics \
       --cluster-ramsize 2048 --cluster-index-ramsize 1024 \
       --cluster-eventing-ramsize 1024 --cluster-fts-ramsize 1024 \
       --cluster-analytics-ramsize 1024 --cluster-fts-ramsize 1024 \
       --index-storage-setting default

      If you want to set the port number you can do so with the --cluster-port option. In the example below, a cluster is setup on port 5000 and starts only the data service. The memory quota of the data service is set to 2048MiB.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
       --cluster-password password --services data --cluster-ramsize 2048 \
       --cluster-port 5000

      DISCUSSION

      The cluster-init subcommand sets up the first node on a Couchbase cluster. To set per node settings such as the data storage directory, index storage directory, or hostname see the node-init command. To add nodes to a currently initialized cluster use the server-add command. Some cluster settings may be changed after a cluster is initialized. Use the setting-cluster command to edit these settings.

      ENVIRONMENT AND CONFIGURATION VARIABLES

      CB_REST_USERNAME

      Specifies the username to use when executing the command. This environment variable allows you to specify a default argument for the -u/--username argument on the command line.

      CB_REST_PASSWORD

      Specifies the password of the user executing the command. This environment variable allows you to specify a default argument for the -p/--password argument on the command line. It also allows the user to ensure that their password are not cached in their command line history.

      COUCHBASE-CLI

      Part of the couchbase-cli suite