A newer version of this documentation is available.

View Latest

Initialize the Cluster

Following installation, the Couchbase cluster must be initialized. You can achieve this by means of the any of the following utilities: the Couchbase Web Console; the Couchbase Command Line Interface; or the Couchbase REST API. Instructions for each are provided in this section. All procedures require full administrator-permissions.

Initialize the Cluster Using the Web Console

The Couchbase Web Console is, by default, available on port 8091. Therefore, if your machine can be identified on the network as servera, you can access the Couchbase Web Console by opening http://servera:8091/. Alternatively, you can use an IP address or, if you are working on the machine on which installation was performed, http://localhost:8091. If you have chosen to run Couchbase on a port other than 8091, connect on that specific port.

Once you have connected, to begin setting up Couchbase Server, click the Setup button on the Welcome Screen:

setup screen

The first setup screen, Configure Server, now appears. Proceed as follows.

Step 1: Configure Server

The Configure Server screen lets you choose either to Start a new cluster, or to Join a cluster now. Select one or the other of these options by means of the corresponding radio button: associated, interactive fields are then displayed, by means of which you can provide appropriate input.

The screen also allows you to configure disk storage and your server’s hostname. All the options are described in detail below.

  • Start a new cluster

    By default, the first option, Start a new cluster, is already selected when the screen first appears:

    cluster setup 01

    The displayed fields for Start a New Cluster are as follows:

    • RAM Available: The total RAM available on this node.

    • Services: The available Couchbase services for this node; which are Data, Index, Query, and Full Text. Since you are starting a new cluster, the Data service (which is essential for the cluster) has already been allocated, and its checkbox disabled. If this is a development system, you may add up to three services. Note that on a production system, it is recommended that only one service ever be allocated per node: therefore, if this is indeed a production-system, you are advised not to add another service to this node.

    • Data RAM Quota: The RAM-allocation for the Data service. This should be 256 MB or more. A default quota is provided.

    • Full Text RAM Quota: The RAM-allocation for the Full Text service. This should be 256 MB or more. If this service is selected, a default quota is provided.

    • Index RAM Quota: The RAM-allocation for the Index service. This should be 256 MB or more. If this service is selected, a default quota is provided.

    • Total Per Server: The total RAM used on this node by the Data and any additional services. For good performance, this should be less than %80 of the total available RAM on this node. A default total of %60 is provided. If there are multiple nodes in your cluster, the RAM-total you specify here will also be allocated to each other node.

    • Index Storage Setting: If the Index service has been selected, either Standard Global Secondary Indexes or Memory-Optimized Global Secondary Indexes can be chosen here, by means of radio buttons. See Global Secondary Indexes (GSIs), for details.

    Note that no RAM-allocation option is provided for the Query service, since none is required. Note also that interactive What’s this? elements are provided throughout the screen, in adjacency to certain fields: by hovering over any of these elements with the mouse-cursor, you cause pop-up help-information to be displayed.

    + If you are joining an existing cluster, rather than starting a new cluster, you do not need to enter data into any of the above fields. Instead, click on the radio button Join a cluster now; and proceed as described immediately below.


  • Join a cluster now

    cluster setup 01 join

    If you elect to Join a cluster now, interactive fields are displayed for the...

    • IP Address of the cluster you are joining.

    • Username of the Couchbase Server administrator who is managing the cluster you are joining.

    • Password of the Couchbase Server administrator who is managing the cluster you are joining.

    • Services available. Each (including Data) can be selected by means of an associated checkbox. Select one to three services for a development environment. You are recommended only to set one service for a production environment.

  • Configure Disk Storage

    Whether you are starting a new cluster, or joining one existing, configure disk storage as follows:

    • Database Path: The interactive text-field should contain the location where the database files will be stored. The following default is provided: /Users/user_name/Library/Application Support/Couchbase/var/lib/couchbase/data. The read-only Free field shows the current amount of free space for this location.

    • Indices Path: The interactive text-field should contain the location where indices will be stored. The following default is provided: /Users/user_name/Library/Application Support/Couchbase/var/lib/couchbase/data. The read-only Free field shows the current amount of free space for this location.

    Note that for a production environment, it is recommended that data and indexes should not share the same location.


  • Configure Server Hostname

    Whether you are starting a new cluster, or joining one existing, either enter a node IP or hostname into the editable text-field; or use the default provided.

    Note that a specified hostname will survive node restart. For more details about hostnames, see Using Hostnames.

When you have entered data into all the appropriate fields listed above, click the Next button, at the bottom-right. This dismisses the Configure Server screen, and brings up the Sample Buckets screen.

Step 2: Install Sample Buckets

Couchbase provides sample buckets, which contain data for demonstration and test purposes. The Sample Buckets screen allows you to choose which of these buckets you wish to install. The screen appears as follows:

setup 02

Click the corresponding checkboxes for the sample buckets you wish to to load into the Couchbase Server. Then, click the Next button. This dismisses the Sample Buckets screen, and displays the Create Default Bucket screen.

Step 3: Create a default bucket

setup 03

Creation of a default bucket is optional. The bucket contains no data by default; but can be configured in detail, and used for testing and other purposes. It can be removed after installation, if appropriate; and can be re-added still later.

The Create Default Bucket screen provides interactive configuration options. Note that What’s this? pop-ups can be accessed, for pop-up assistance.

The configuraton options are as follows:

  • Bucket Settings

    This section of the screen establishes the name and type of the bucket. Since it is the default bucket that is being configured, the name (default) has been pre-set. No data-entry is required.

    However, the type of the bucket can be established as either Couchbase or Memcached, by means of radio-buttons. Couchbase is initially selected by default. If you select Memcached, the appearance of the Create Default Bucket screen changes to the following:

    install createDefaultBucketMCD230117

    As shown by the above illustration, the Replicas and Disk I/O Optimization sections have been omitted; since they are not pertinent to memcached buckets.

  • Memory Size

    This section allows the RAM quota for the default bucket to be determined. The interactive Per Node RAM Quota text-field allows memory to be allocated to the default bucket. As you change the number of megabytes, the graphical display to the immediate right of the field changes spontaneously, to demonstrate how much memory for the full cluster is now allocated to this and to other buckets:

    install createDefaultBucketRAM230117

    Total bucket size is also dynamically recalculated.

    The Cache Metadata radio buttons permit the default bucket’s data to be subject either to Value Ejection or Full Ejection. If Value Ejection is selected, when memory is constrained, only the data-value is ejected: the key and metadata remain in memory. If Full Ejection is selected, everything (including metadata, key, and value) is ejected. Generally, Value Ejection favors performance at the expense of memory; and Full Ejection vice versa. See Database Engine Architecture, for more information.

  • Replicas

    This section allows replica-creation to be enabled and managed. To enable, check the Enable checkbox. The number of replica-copies to be created and maintained is determined by means of the Number of replica (backup) copies pulldown menu, which allows a value from 1 to 3 to be selected. By checking the View index replicas checkbox, you ensure that view indexes, as well as data, are replicated.

  • Disk I/O Optimization

    This section allows the bucket’s disk I/O priority to be specified. Radio-buttons allow Low or High to be chosen. These settings determine whether I/O tasks are enqueued in low or high priority task-queues: with the high priority resulting in faster processing. The default is Low. See Database Engine Architecture, for further information.

  • Flush

    This section allows flushing to be enabled. If it is enabled, and flushing is performed, items in the bucket are removed as soon as possible. See Flush a Bucket, for details.

If you do not wish to configure and use the Default Bucket, click on the Skip button. If you do wish to use it, once you have entered your configuration-preferences, click on the Next button.

The Create Default Bucket setup screen is now dismissed, and the Notifications screen appears.

Step 4: Notifications


The Notifications screen features two key areas, which are as follows:

  • Update Notifications

    If you check the Enable software update notifications checkbox, provided that the current node is connected to the internet, the Couchbase Server version-numbers corresponding to each node in your cluster will be anonymously sent to Couchbase: this information is used by Couchbase over time, to provide you with appropriate updates, and to help with product-improvement. If you additionally choose (based on subsequent fields in this dialog) to provide registration-information, your email-address will be added to the Couchbase community mailing-list, so that you can periodically receive Couchbase news and product-information. (You can unsubscribe from the mailing-list at any time using the Unsubscribe link, provided in each newsletter.)

  • Product Registration

    Register your product, by entering your Email, First name, Last name, and Comapny. Then, check the checkbox whereby you agree to accept terms and conditions.

When you have finished entering information, click on the Next button. This dismisses the Notifications screen, and displays the Configure Server screen.

Step 5: Configure server

To create a cluster, you must assign yourself administrative credentials: these will be used on all nodes in the cluster you are creating. This is accomplished by means of the Configure Server screen:

setup 05

Enter an appropriate username (this defaults to Administrator), and a password; and then verify the password. Then, click on the Next button.

This concludes the Couchbase Server initialization-process.

Step 6: Explore Couchbase Server

Couchbase Server is now running and ready to use. The starting screen for the new Couchbase Server, Cluster Overview, appears as follows:

setup 06

Using the Couchbase Web Console, you can now explore all the administrative options at your disposal. For example, by accessing Data Buckets, you can examine the data-contents of the buckets you previously may have chosen to install.

setup 07

Initialize the Cluster Using the CLI

Rather than using the Couchbase Web Console, you may elect to initialize your Couchbase cluster by means of the Couchbase CLI (Command Line Interface).

The following CLI syntax can be used for initial set-up of a single-node Couchbase Server-cluster. It allows the establishing of administrative credentials, and of port number. It adds all services; sets separate RAM quotas for Data, Index, and Search services, and sets the index storage-option (the default being to support memory-optimized global indexes):

couchbase-cli cluster-init OPTIONS:
      --cluster-username=USER           // new admin username
      --cluster-password=PASSWORD       // new admin password
      --cluster-port=PORT               // new cluster REST/http port
      --services=data,index,query,fts   // services that server runs
      --cluster-ramsize=RAMSIZEMB       // per node data service ram quota in MB
      --cluster-index-ramsize=RAMSIZEMB // per node index service ram quota in MB
      --cluster-fts-ramsize=RAMSIZEMB   // per node index service ram quota in MB
      --index-storage-setting=SETTING   // index storage type [default, memopt]

Initialize the Cluster Using the REST API

The third option for performing Couchbase cluster-initialization is provided by the Couchbase REST API.

The following REST API examples are used to set up a single-node Couchbase Server cluster with three services, administrative credentials, and a RAM quota:


Set up services:

curl -u [admin-name]:[password] -v
-X POST http://[localhost]:8091/node/controller/setupServices
-d services=[kv | index | n1ql | fts]

Initialize a node:

curl -v -X POST http://[localhost]:8091/nodes/self/controller/settings
-d path=[location] -d index_path=[location]

Set up your administrator-username and password:

curl -v -X POST http://[localhost]:8091/settings/web -d password=[password] -d username=[admin-name]

Set up a bucket:

curl -v -X POST http://[localhost]:8091/pools/default/buckets -d ramQuotaMB=[value]

Set up the index RAM quota (to be applied across the entire cluster):

curl -u username=[admin-name]&password=[password]  -X POST http://[localhost]:8091/pools/default
-d memoryQuota=[value] -d indexMemoryQuota=[value]


// Set up services. (Note that %2C is the ASCII Hex mapping to the comma character.)

curl -u Administrator:password -v -X POST \
-d 'services=kv%2Cn1ql%2Cindex%2Cfts'
// Initialize a node. (Note that %2F is the ASCII Hex mapping to the forward-slash
// character.)

curl -v -X POST \
-d 'path=%2Fopt%2Fcouchbase%2Fvar%2Flib%2Fcouchbase%2Fdata&index_path= \
// Set up your administrator-username and password.

curl -v -X POST \
-d 'password=password&username=Administrator&port=SAME'
// Set up a bucket.

curl -u Administrator:password -v -X POST\
default/buckets -d 'flushEnabled=1&threadsNumber=3&replicaIndex\
=0&replicaNumber=0&evictionPolicy= valueOnly&ramQuotaMB=597&\
// Set up the index RAM quota (to be applied across the entire cluster).

curl -u Administrator:password -X POST \
-d 'memoryQuota=5000' -d 'indexMemoryQuota=269'