A newer version of this documentation is available.

View Latest

Initializing the Cluster

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

    Access the Couchbase 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, the Welcome screen appears:


    The Welcome screen lets you either Setup New Cluster, or Join Existing Cluster. Information on joining an existing cluster is provided below, in the section Join an Existing Cluster. To set up a new cluster, left-click on Setup New Cluster.

    Set Up a New Cluster

    The New Cluster screen now appears, as follows:


    The fields displayed on the screen are:

    • Cluster Name: Your choice of name for the cluster to be created.

    • Create Admin Username: Your choice of username, for yourself: the Full Administrator for this cluster. You will have read-write access to all Couchbase Server resources; including the ability to create new users with defined roles and corresponding privileges.

      Note that Couchbase Server prohibits use of the following characters in usernames: ( ) < > @ , ; : \ " / [ ] ? = { }. Usernames may not be more than 128 UTF-8 characters in length; and it is recommended that they be no more than 64 UTF-8 characters in length, in order to ensure successful onscreen display.

    • Your choice of password, for yourself: the Full Administrator for this cluster. The only default format-requirement is that the password be at least 6 characters in length. However, following cluster-initialization, you can modify (and indeed strengthen) the default password-policy, by means of the Couchbase CLI setting-password-policy command.

    When you have entered appropriate data into each field, left-click on the Next: Accept Terms button, at the lower right.

    Accept Terms

    The New Cluster screen now changes, to show the Terms and Conditions for the Enterprise Edition of Couchbase Server:


    Check the I accept the terms & conditions checkbox. Then, to register for updates, left-click on the right-facing arrowhead, adjacent to the Register for updates notification. The screen now expands vertically, as follows:


    To receive updates, fill out the four newly displayed fields with your first and last name, company-name, and email-address. 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. 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.)

    You now have two options for proceeding. If you left-click on the Finish With Defaults button, cluster-initialization is performed with default settings, provided by Couchbase; the Couchbase Web Console Dashboard appears, and your configuration is complete. However, if you wish to customize those settings, left-click on the Configure Disk, Memory, Services button, and proceed as follows.

    Configure Couchbase Server

    The Configure screen now appears, as follows:


    The displayed fields are:

    • Host Name/IP Address: Enter the hostname or IP address for the machine on which you are configuring Couchbase Server.

    • Data Disk Path: Enter the location on the current node where the database files will be stored. The following default is provided: /Users/username/Library/Application Support/Couchbase/var/lib/couchbase/data. The read-only Free field shows the current amount of free space for this location.

    • Indexes Disk Path: Enter the location on the current node where indices will be stored. The following default is provided: /Users/username/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.

    • Couchase Memory Quotas: A series of fields that allows you to specify how much memory should be allocated to each service you select for both the current node and for each node you may subsequently add to the cluster. Each service can be selected by checking a checkbox, and then specifying the total number of megabytes to be assigned to the service. In each case, a memory quota is suggested, and a minimum quota is required. The sum of all quotas must be within the total amount of available RAM for the current node.

      • Data Service: Since you are starting a new cluster, the Data service (which is essential for the cluster) has been allocated with 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.

      • Index Service: Selection and RAM-allocation to support Global Secondary Indexes. This should be 256 MB or more. If this service is selected, a default quota is provided.

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

      • Query Service: No RAM-allocation is required for this service.

      The total memory quota you have allocated is displayed below these fields, towards the right. The total RAM available is displayed below this figure, at the center. If your memory allocation is excessive, a notification warns you, and you must lessen your allocation.

    • 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.

    When you have finished entering your configuration-details, left-click on the Save & Finish button, at the lower right. This configures the server accordingly, and brings up the Couchbase Web Console Dashboard, for the first time.


    New-Cluster Set-Up: Next Steps

    If this is the first server in the cluster, a notification appears, stating that no buckets are currently defined. A bucket is the principal unit of data-storage used by Couchbase Server. In order to save and subsequently access documents and other objects, you must create one or more buckets.

    As specified by the notification, you can go to Buckets, and begin bucket-creation; or add a sample bucket: left-click on the links provided. A description of how to create, edit, flush, and delete buckets can be found in the section Setting Up Buckets. An architectural description of buckets can be found in the section Buckets. (There are three different kinds of bucket, so you may wish to familiarize yourself with their properties, before you start bucket-creation.) Note that sample buckets already contain data, and so are ready for your immediate experimentation and testing.

    The buckets that you create must be accessed securely: therefore, Couchbase Server provides a system of Role-Based Access Control (RBAC), which must be used by administrators and applications that wish to access buckets. Each administrator and application is considered to be a user, and must perform bucket-access by passing a username and password. For information on how to set up RBAC users so that they can access the buckets you create, see Authorization.

    Join an Existing Cluster

    If, while the Welcome Screen is still displayed, you left-click on Join Existing Cluster, the Join Cluster screen appears:


    The interactive fields Cluster Host Name/IP Address, Cluster Admin Username, and Cluster Admin Password require you to enter information already defined by the Full Administrator for the cluster-host: see Set Up a New Cluster, above.

    When you have entered the appropriate details, you can left-click on the Join With Default Configuration button, at the lower right, in order to join the cluster using a default configuration. Note that the default configuration is not recommended for production environments. To change the default configuration, or to review its details, left-click on the right-pointing arrowhead adjacent to the Configure Services & Settings For This Node notice.

    The screen now expands vertically, as shown below:


    Newly displayed fields show default values for the four Couchbase services (with each box checked, indicating that each will be added to this node by default), the Host Name/IP Address for the current node, and default paths for Data and Indexes. Specify hostname or IP address, and data and index paths as described above, in Set Up a New Cluster.

    Note that the checkboxes for the services are not accompanied by fields whereby memory quotas might be specified: this is because such quotas are expected already to have been specified by the Full Administrator (for example, during configuration of the principal cluster-host). However, in some circumstances, node-addition may require addition of a service not previously configured: in which case memory-quota specification is indeed required, and will be prompted for. For example, uncheck the checkboxes for Query Service and Search Service. The checkbox-display now appears as follows:


    Note that due to this change, the button at the lower right has been renamed:


    Left-click on this button, to save the configurations you have specified. If the existing cluster previously had (say) only the Data service defined, the New Service Settings dialog now appears:


    This dialog acknowledges that the Index has been added to the cluster for the first time, and provides the opportunity to edit both of the services now featured (Data and Index), and also to make a selection for the Index Storage Setting; as is now required due to your addition of the Index service. All modifications you now make are applied to each node in the cluster.

    When you have made the appropriate changes, left-click on the Save Settings button. The Couchbase Web Console Dashboard for the current node now appears — with a notification confirming the successful saving of a new memory quota:


    The new node has now been successfully added to the existing cluster.

    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]
      -d port=[desired-rest-api-port|SAME]

    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 the index RAM quota (to be applied across the entire cluster).
    curl -u Administrator:password -X POST \
    -d 'memoryQuota=5000' -d 'indexMemoryQuota=269'