A newer version of this documentation is available.

View Latest

AWS Marketplace

Amazon Web Services (AWS) is a collection of web services that make up a cloud-computing platform.

The recommended and often easiest way to get started is to use the Couchbase Server Amazon Machine Images (AMIs).

AMIs provides the information required to launch an instance of a virtual server in the cloud and are available within the AWS Marketplace.

In this guide, command line examples that begin with $ are run in a standard Linux shell.

Installing with AMI

You can find the Couchbase Server’s Amazon Machine Images (AMIs) by searching for couchbase in the Amazon’s EC2 portal.

To install the Couchbase Server AMI:

  1. Visit the page that contains Couchbase Server AMIs.

  2. When prompted, sign into your AWS account.

  3. Select the AWS Region where you want to launch your Couchbase Server instance in the Region section.

  4. Choose your preferred instance type in the Amazon EC2 Instance Type section.

  5. Choose a Key Pair to associate with the instance in the Key Pair section.

  6. Select the Key Pair you want to use when connecting to the instance over Secure Shell (SSH) in the Key Pair section.

  7. Click Launch with 1-Click to create your new instance.

  8. After the instance is created, you will be presented with the deployment details. Take note of the Instance ID.

  9. Sign into the AWS Management Console, select EC2 and click the ID for the instance just created. In the instance detail panel, make a note of the Public DNS hostname. You will need this to log into your Couchbase Server installation.

  10. To connect to your Couchbase Server installation, open a browser and connect to the instance URL on port 8091. For example,


    Answer the prompts for the username and password for the Couchbase Server web console:

    • Username is Administrator

    • Password is your instance ID

  11. When you have successfully logged in, you should be presented with the Couchbase Server Administration Web Console Cluster Overview window. The server is automatically configured for you.

After the instance has started, it will operate just like any Couchbase Server instance. This single instance can operate independently, or can be added to a group of similar instances to create a cluster.

Manual Installation

Manual AWS installation using the Amazon Linux 64-bit AMI.

To install Couchbase Server manually, follow these steps:

  1. Launch an Amazon EC2 instance using the AMI of your choice.

  2. Create an EBS volume to use for your Couchbase Server storage, and attach it to the instance.

  3. Connect to the instance over SSH.

  4. Install the openssl098e that Couchbase Server X.X.X requires.

    $ sudo yum install openssl098e

    You might also want to check the latest AWS security bulletin to upgrade your OpenSSL version if it is affected.

  5. Download and install the Couchbase Server package. At the SSH command prompt, type the following, and then press Enter:

    $ sudo rpm -i couchbase-server-enterprise_x86_64_X.X.X.rpm
  6. Couchbase Server will start automatically when the installation is complete. The setup process, which configures Couchbase Server and sets the data location and other details, is run separately.

  7. Make a file system on your Amazon Elastic Block Store (EBS) volume:

    $ sudo mkfs -t ext4
  8. Make a directory and mount the file system:

    $ sudo mkdir -p /data/db/
  9. Edit your file system configuration to enumerate the volume on startup:

    $ sudo su
               $ sudo echo '/dev/sdf /data/db auto noatime,noexec,nodiratime 0 0' >> /etc/fstab
               $ exit
  10. Mount the volume:

    $ sudo mount -a /dev/sdf /data/db
  11. Set the owner of the mounted volume:

    $ sudo chown couchbase /data/db
  12. Configure the instance to use the Amazon EBS directory for storage:

    $ /opt/couchbase/bin/couchbase-cli node-init -c localhost:8091 --node-init-data- path=/data/db
  13. Set the security group for the new instance, allowing connectivity for ports 8091, 8092, 11210, 4369 and 21100 to 21199. For communication between clients and instances, you need only ports 8091, 8092, and 11210. For the complete list of ports used for Couchbase Server, see Network Configuration.

  14. Initialize the cluster by setting the username, password, cluster port (default 8091) and RAM allocated to Couchbase Server for data storage. To do so, access the Couchbase Server setup service through the Web-based administration console, which is initially exposed on port 8091. If you have not configured a public IP address, or if you want to automate the process, you can use the command-line tools to perform the setup operation as follows:

    $ /opt/couchbase/bin/couchbase-cli cluster-init -c localhost:8091 \ --cluster-init-username=Administrator \
               --cluster-init-password=password \
               --cluster-init-port=8091 \
  15. When the cluster is initialized, you can access the Web Administration console by visiting the public DNS on the port configured in the command in the previous step, for example, http://publicdns:8091. You must log in with the username and password configured in the previous step.

Best Practices

Handling Instance Reboot in the Cloud

Many cloud providers warn users that they need to reboot certain instances for maintenance. Couchbase Server ensures these reboots won’t disrupt your application. Take the following steps to make that happen:

  1. Install Couchbase Server on the new node.

  2. From Couchbase Web Console, add the new node to the cluster.

  3. From Couchbase Web Console, remove the node that you wish to reboot.

  4. Rebalance the cluster.

  5. Shut down the instance.

Local Storage

Dealing with local storage is not very much different than a datacenter deployment. However, EC2 provides an interesting solution: using the EBS storage you can prevent data loss when an instance fails. Writing Couchbase Server data and configuration to EBS creates a reliable medium of storage. Using EBS is definitely not required, but you should make sure to follow the best practices around performing backups. Keep in mind that you will have to update the per-node disk path when configuring Couchbase Server to the point you have mounted an external volume.

Handling IP Addresses Changes

When you use Couchbase Server in the cloud, server nodes can use internal or public IP addresses. Because IP addresses in the cloud can change quite frequently, you can configure Couchbase Server to use a hostname instead of an IP address. For Amazon EC2,Amazon-generated hostnames are recommended that will automatically resolve to either an internal or external address. By default, Couchbase Server uses specific IP addresses as a unique identifier. If the IP changes, an individual node will not be able to identify its own address, and other servers in the same cluster will not be able to access it. To configure Couchbase Server instances in the cloud to use hostnames, follow the steps later in this section. Make sure that your hostname always resolves to the IP address of the node. This can be accomplished by using a dynamic DNS service such as DNSMadeEasy which will allow you to automatically update the hostname when an underlying IP address changes. The following steps completely destroy any data and configuration from the node, so you should start with a fresh Couchbase Server installation. If you already have a running cluster, you can rebalance a node out of the cluster, make the change, and then rebalance it back into the cluster. Nodes with both IPs and hostnames can exist in the same cluster. When you set the IP address using this method, you should not specify the address as localhost or as this will be invalid when used as the identifier for multiple nodes within the cluster. Instead, use the correct IP address for your host.

Linux and Windows 2.1 and Above

As a rule, you should set the hostname before you add a node to a cluster. You can also provide a hostname in these ways: when you install a Couchbase Server node or when you do a REST API call before the node is part of a cluster. You can also add a hostname to an existing cluster for an online upgrade. If you restart, any hostname you establish with one of these methods will be used.

Linux and Windows 2.0.1 and Earlier

For Couchbase Server 2.0.1 and earlier you must follow a manual process where you edit configuration files for each node, as described for Couchbase Server in the cloud.

Security Groups/Firewall Settings

It’s important to make sure you have both allowed AND restricted access to the appropriate ports in a Couchbase Server deployment. Nodes must be able to talk to one another on various ports, and it is important to restrict both external and internal access to only authorized individuals. Unlike a typical datacenter deployment, cloud systems are open to the world by default, and steps must be taken to restrict access.

Instance Types

Prior to 4.x.x, the general recommendation is to use similar instance types for all the nodes in the cluster, but with Multidimensional Scaling you could take advantage of different instance types for Index and Query nodes as these nodes require less storage but more CPU cores and more RAM, and for data nodes choose similar instance types.