Deploy Your First Cluster

    After signing up for a Couchbase Cloud account and creating an organization, you can deploy your first cluster and begin testing out Couchbase Cloud features.


    The procedures on this page assume the following:


    This guide assumes that you are the first user in your organization (and thus have Organization Admin privileges). If you have been invited to an existing organization, your experience may vary.

    Sign Into Couchbase Cloud

    Go to to sign in.

    After signing in, you’ll be brought to your organization’s Dashboard tab.

    The 'Dashboard' tab for a brand new organization. A welcome message is displayed with a button labeled 'Get Started'.

    The Dashboard is the best place to see a summary of all the resources and alerts that you are authorized to view in your organization. However, if you are the first person in your organization and have not yet created any resources, the Dashboard will display a welcome message as seen in the image above.

    If you’re a member of more than one organization, you’ll be able to switch between organizations using the organization selector located at the top of the main navigation menu. It’s important to ensure that the desired organization is selected before performing any action in the Couchbase Cloud UI.

    The organization selector.

    Get Started

    1. If you’re the first user in your organization to configure resources, the Get Started button will be visible on the Dashboard tab. Click it to begin.

      If another user has already configured resources in your organization, then the Get Started button may not be present. If this is the case, click the Create Cluster button instead and follow the instructions on the Create a Cluster page. Once finished, return here to move on to Next Steps.

    2. Add your Activation ID.

      If an Activation ID hasn’t been added to your organization yet, the Activation ID fly-out menu will appear prompting you to add one. You need to enter either a Trial Activation ID that you received as part of a Free Trial program, or a Paid Activation ID that you received from Couchbase Sales.

      After entering your Activation ID, click Activate.

    After successfully adding your Activation ID, the Get Started fly-out appears.

    The 'Get Started' fly-out menu.

    Step 1: Connect a Cloud

    Couchbase Cloud needs to establish a connection to your cloud provider in order to create a virtual private cloud (VPC) within your cloud provider account. These VPCs are referred to as Clouds, and they are leveraged by Couchbase Cloud to provision and manage clusters in your cloud provider account.

    1. Enter the cloud connection details.

      Service Provider

      Select your cloud provider from the drop-down list.

      Cloud Name

      Enter a name for the connected cloud.

      This is the name that users in your organization will see in the Couchbase Cloud UI, both in the Clouds tab, and when deploying clusters. It can be helpful to use a descriptive name so that other users can easily identify the connected cloud.
      Available Regions

      Select a cloud provider region from the drop-down list. This is the region in your cloud provider where Couchbase Cloud will set up a VPC environment. All clusters that use this connected cloud will be deployed in the selected region.

      CIDR Block

      Enter an IP range in CIDR notation. Couchbase cloud will use IPs in this range for deployed resources. Unless you plan on configuring a peering connection between your Couchbase cluster and your application server, you can feel free to accept the default CIDR block.

      If you do plan on configuring a peering connection for any of the clusters deployed on this connected cloud, then you must ensure that the CIDR block you enter does not overlap with the CIDR block of your application server. If you don’t know the CIDR block of your application server, or if you’re unsure whether or not you will need to configure a peering connection in the future, you can still move forward using the default CIDR block and just connect another cloud using a different CIDR block should it be necessary in the future.

    2. Once you’ve configured the required fields, click Connect Cloud.

      Your cloud provider’s console will open in a new browser tab. If the console doesn’t open, make sure that your browser is configured to allow pop-up windows from Couchbase Cloud and then try clicking the button again.

    3. Log into your cloud provider using an account that has sufficient privileges and capabilities for deploying Couchbase Cloud resources.

    4. Deploy the stack template.

      After logging into your cloud provider’s console, a pre-configured resource template will be displayed in the region that you specified. This template contains the necessary configuration for Couchbase Cloud to be able to connect to your cloud provider and deploy a VPC under your account.

      For AWS, the resource template will be in the form of a CloudFormation template:

      AWS 'Quick create stack' template showing several pre-filled fields, a required IAM acknowledgment checkbox, and buttons at the bottom to 'Create change set' or 'Create stack'.

      You must deploy the template to continue. In the case of AWS, deploy the template by checking the box labeled I acknowledge that AWS CloudFormation might create IAM resources with custom names and then clicking Create stack.

      Couchbase Cloud provisions and maintains VPC resources in your cloud provider account for each connected cloud. These resources will incur a nominal infrastructure cost in your cloud provider account for the lifecycle of the connected cloud.

      Once the stack begins to deploy, return to the Couchbase Cloud UI. (It’s safe to close your cloud provider console, but you may need to return to it should any issues occur during the connection process.) The connection details in the Get Started fly-out menu will indicate that Couchbase Cloud is waiting for your cloud provider. Once the basic stack deployment is complete, and the initial connection is established, a series of status bars will appear, each representing a different step in the VPC deployment process.

      For AWS, the basic stack deployment process takes around 10 minutes to complete. If after 15 minutes Couchbase Cloud still hasn’t received a connection attempt from your cloud provider, the connection will time out. If this occurs, refer to the troubleshooting note below.

      You’ll know that the entire VPC deployment was successful once all of the steps are complete, and the Connection Status changes to Connected.

      The cloud section of the 'Get Started' fly-out menu, showing all connection steps successfully completed and the 'Connection Status' displaying as 'Connected'.

      Once you’ve successfully created the connected cloud, you can move on to Step 2: Name Your Project and Cluster.

      Troubleshooting Failed Connections

      If the basic stack deployment takes longer than 15 minutes, Couchbase Cloud assumes the operation has failed and will time out the connection. If no specific error is reported in the Couchbase Cloud UI, it can occasionally be the case that cloud provider performance is to blame, and simply retrying the connection will solve the issue. However, the most common issues that occur with connecting a cloud are caused by the cloud provider account not having adequate permissions and quotas for deploying the basic stack and associated VPC resources.

      If an error or timeout occurs before the cloud connection status bars appear in the Couchbase Cloud UI, then it’s likely that a permissions issue caused the basic stack deployment to fail. If this is the case, then you will need to inspect the stack within your cloud provider console to determine which permissions issues caused the error.

      However, if the cloud connection status bars have already appeared in the Couchbase Cloud UI, it means that the basic stack deployment was successful, and any further permissions or quota issues will be related to the deployment of VPC resources and will be reported in the Couchbase Cloud UI. Should an issue be reported that halts any of the status bars, Couchbase Cloud will re-attempt deployment every five minutes for five days.

      Refer to Cloud Provider Requirements for details about the specific account permissions and quotas that are required by Couchbase Cloud.

    Step 2: Name Your Project and Cluster

    Each cluster must be created within a project. Projects are the logical mechanism for grouping and managing clusters within your organization.

    Since there are no projects to select yet, one will be created for you. Simply enter a name for the project in the Project Name field.

    Future members of the project will see this name in the Couchbase Cloud UI. It can be helpful to pick a name that describes the purpose and/or logical owner of the project, making it easier to find and identify in the Couchbase Cloud UI.

    Next, enter a name for your cluster in the Cluster Name field. (Note that this isn’t the cluster’s hostname, and can be changed at any time.)

    Once you’ve entered names for your project and cluster, click Create Project & Cluster and move on to Configure and Deploy the Cluster.

    Configure and Deploy the Cluster

    Now that you’ve connected a cloud, created a project, and given a name to your cluster, the next step is to configure and deploy the cluster.

    The `Cluster Sizing` screen showing the 'Quick Start' template selected.

    The Cluster Sizing screen provides multiple different approaches to help you size and configure your cluster, but the simplest approach is to use one of the pre-defined cluster templates. (You can read more about the other approaches in Cluster Sizing.)

    At this point, the cluster is saved in a draft state. If you leave the cluster configuration screen, you can always pick up where you left off by going to the Clusters tab in the main navigation and then clicking on the draft cluster.
    1. Select a cluster template.

      There are several templates to choose from, with the Quick Start template providing the best all-around cluster configuration for experimenting with Couchbase features and services.

    2. Select the template size.

      After selecting a template, the Deployment Configuration panel shows the template’s configuration. Use the size toggle to switch between different sizes of the template.

      For the Quick Start template, there are two sizes available: XS and S. If you switch between these two sizes, you’ll notice that the only difference between them is the number of Nodes (one node vs. three nodes). One-node clusters have several limitations, but you can still use the XS size as an affordable way to experiment with most Couchbase features.

    3. Once you’ve configured the cluster to your liking, click Next.

      This brings you to the Deploy Cluster screen.

      The 'Deploy Cluster' screen.
    4. Review the cluster configuration and select a Support Plan.

      The Deploy Cluster screen shows a summary of the configuration details. Review the configuration to ensure that it meets your expectations. You can click the Prev button at the bottom of the page to go back and make any necessary changes.

      Further down the page, in the Select Support Plan section, you must select a Support Time Zone and a Support Plan for the cluster.

      1. Use the Select Support Time Zone drop-down menu to select the Support Time Zone that is most appropriate for the cluster (such as when cluster administrators are able to interact with Couchbase Support staff).

      2. Select one of the available Support Plans.

        If you are using a Trial Activation ID, only the Free Trial Support Plan is available.

    5. Once you’re satisfied with the cluster configuration, click Deploy.

      Couchbase Cloud will proceed with automatically deploying the cluster on your connected cloud.

      Once the deployment begins, Couchbase Cloud will provision and maintain cluster resources in your cloud account. These resources will incur infrastructure cost in your cloud account for the lifecycle of the cluster.

      A cluster will generally take up to 15 minutes to deploy, though it can take longer depending on certain factors such as cluster size and cloud provider performance.

      Leaving the page will not affect deployment progress, and you can feel free to return to the cluster page at any time. You’ll receive a notification when the deployment is done.

    When you return to the cluster after it has been successfully deployed, you will be taken to the cluster’s Connect tab.

    Next Steps

    Now that you’ve connected a cloud, created a project, and deployed your first cluster, you can move on to the next step: Configure Access to Your Cluster.