CloudUsing Couchbase Server on AWS Tutorial

Using Couchbase Server on AWS Tutorial

Couchbase Server is a distributed, NoSQL database based on the document model. Couchbase is based on a schema-less data model using JSON documents for storage. Couchbase Server also provides a SQL-like database query language called N1QL that may be used to directly query JSON stored in Couchbase server using SQL. Some of the benefits of using Couchbase are flexible data model, SQL querying and indexing, support for migrating from relational databases, a Couchbase Hadoop connector for connecting to an Apache Hadoop cluster, Couchbase Kafka connector for streaming data from Couchbase Server to Kafka, scalability, and high-availability.

Although Couchbase server may be installed on a bare-metal EC2 instance, AWS provides some pre-built AMIs for Couchbase. The pre-built AMIs available on AWS are the following:

  • Couchbase Server Community Edition 4.5.0 (Linux/Unix, Amazon Linux 2016.03 | 64-bit Amazon Machine Image (AMI))
  • Couchbase Server Enterprise Edition (Silver) 4.6.0 (Linux/Unix, Amazon Linux 2016.03 | 64-bit Amazon Machine Image (AMI))
  • Couchbase Server Enterprise Edition (Gold) 4.6.0 (Linux/Unix, Amazon Linux 2016.03 | 64-bit Amazon Machine Image (AMI))

The Enterprise editions provide secure cross data center replication and rack awareness to enable high availability with AWS availability zones. The Couchbase Server Enterprise editions include a free trial for initial evaluation. In this tutorial, we shall discuss using the Couchbase Server Community Edition 4.5.0 on AWS. This tutorial has the following sections:

Setting the Environment

The only pre-requisite is an AWS account, which may be created at if you do not already have one. To access the AWS EC2 instance for the Couchbase Server, a local Linux installation is required.

Launching a Couchbase Server Community Edition Instance

First, we need to launch an AWS EC2 instance using the AMI for Couchbase Server Community Edition 4.5.0. Select the EC2 service in the AWS services console. Click Launch Instance to launch an instance. Select the AWS Marketplace link and search for “couchbase.” The AMIs for Couchbase server get listed. Select the Couchbase Server Community Edition (based on package: couchbase-server-community-4.5.0-centos6.x86_64.rpm) AMI with the Select button, as shown in Figure 1.

Selecting the Couchbase Server AMI on AWS EC2
Figure 1: Selecting the Couchbase Server AMI on AWS EC2

Next, the detail dialog for the AMI gets displayed, in which you need to click Continue. Choose an Instance Type from those listed. Micro instances are eligible for the AWS free usage tier, but we shall need a slightly larger capacity instance type. The memory optimized r3xlarge instance type, which has 2 vCPUs, 15 GiB memory, 1×32 (SSD) instance storage, moderate network performance, and with IPv6 support is pre-selected. Click Next:Configure Instance Details. In Configure Instance Details, select Number of instances as 1 (the default), and configure the Network VPC and Subnet to launch the instance in. Auto-assign Public IP should be set to Enable. Click Next: Add Storage. Select the default settings for Add Storage, which includes an Instance Store 0 Volume type. Click Next: Add Tags. No tags need to be added in Add Tags.

Click Next:Configure Security Group. Select the default settings for Security Group, which include Custom TCP Rules from any source ( for ports 22, 8091, 11211, 11210, and 4369. Click Review and Launch. In the Boot from General Purpose (SSD) dialog, keep the default setting of “Make General Purpose (SSD) the default boot volume for all instance launches” and click Next. In Review Instance Launch, click Launch. In the dialog to select or create a key pair, select the “Create a new Key pair” option and specify a Key pair name (couchbase) and click Download Key Pair. We shall need the Key pair when we SSH log in into the EC2 instance. Click Launch Instances. An EC2 instance hosting pre-installed Couchbase Server software gets launched. Copy the IPv4 Public IP from the EC2 Console (shown in Figure 2), which we shall need to log in to the instance.

IPv4 Public IP
Figure 2: IPv4 Public IP

The EC2 instance for Couchbase Server is pre-configured to store data and logs in an EBS volume mounted at data-path: /mnt/ebs/db. The EBS volume is shown in Figure 3.

EBS Volume for Couchbase Server data Figure 3: EBS Volume for Couchbase Server data

Copy the Key pair couchbase.pem to a local Linux machine and set the permissions as follows:

chmod 400 couchbase.pem

Next, create a SSH Login to the EC2 instance using the Key Pair and Public IP Address.

ssh -i "couchbase.pem" ec2-user@

The Amazon Linux instance command prompt gets displayed, as shown in Figure 4.

Amazon Linux
Figure 4: Amazon Linux

Update the packages with the sudo yum update command, as shown in Figure 5.

Updating the packages
Figure 5: Updating the packages

The Couchbase Server software is installed into software-path: /opt/couchbase.

Configuring the First Node

The Couchbase Server is ready to be used and accessed from a Web console. The default user name to access the Wen console is “Administrator” and the default password is the Instance ID, which may be obtained from the EC2 Console, as shown in Figure 6.

Instance ID
Figure 6: Instance ID

Copy the Instance ID “i-07c10c0992f7b418f” for later use when accessing the Web console. It is recommended to update the password with the following command in which you will substitute the Instance ID, which would be different for different users in the OLD_PASSWORD variable, and provide a new password in the NEW_PASSWORD variable. The cluster RAM size should be set to an integer to specify the MB setting for the cluster RAM size, with a minimum setting of 256.

   /opt/couchbase/bin/couchbase-cli cluster-init 
      -u Administrator -p OLD_PASSWORD 

The Couchbase Server default node gets configured to the new password and cluster RAM size, as shown in Figure 7.

Configuring the default node
Figure 7: Configuring the default node

Accessing the Server’s Web Console

The Couchbase Server’s Web console may be accessed at URL http://HOST:8091. The HOST variable in the Web console URL is the Public DNS of the EC2 instance on which the Couchbase Server software is hosted. The Public DNS may be obtained from the EC2 Console, as shown in Figure 8.

Public DNS
Figure 8: Public DNS

Access the Couchbase Server Web Console in a Web browser with URL http://HOST:8091, using the Public DNS for HOST. The login page for the Web console gets displayed, as shown in Figure 9.

Login Server for Couchbase Server Web Console
Figure 9: Login Server for Couchbase Server Web Console

Specify Username as “Administrator” and Password as the new password set in the preceding section. Click Sign In, as shown in Figure 10.

Login page for Couchbase Server Web Console
Figure 10: Login page for Couchbase Server Web Console

The Web Console gets displayed for various tabs such as Overview, Server Nodes, Data Buckets, Query, Indexes, XDCR, Security, Log, and Settings. Click the Server Nodes tab for the Servers to display the Server Node, as shown in Figure 11.

Server nodes
Figure 11: Server nodes

The Settings tab displays the cluster settings including the Cluster RAM Quota, as shown in Figure 12.

Cluster settings
Figure 12: Cluster settings

The subsequent sections are not any different than for a Couchbase Server running on a different platform and are included for completeness for those starting with using Couchbase Server.

Creating a Data Bucket

To be able to add data in the form of JSON documents to the Couchbase Server, a data bucket needs to be created. Click the Data Buckets tab to create a data bucket. Subsequently, click Create New Data Bucket, as shown in Figure 13.

Create New Data Bucket Figure 13: Create New Data Bucket

In the Create Bucket dialog, specify a Bucket Name (wlslog), as shown in Figure 14, and keep the default setting for Bucket Type as “Couchbase.” Keep the default settings for Memory Size and Access Control.

Create Bucket Figure 14: Create Bucket

Keep the default settings for Replicas, which are set to Enable, and Disk I/O Optimization, which is set to disk I/O priority Low. Set Flush to Enable and click Create, as shown in Figure 15.

Creating a Couchbase Server Bucket
Figure 15: Creating a Couchbase Server Bucket

A new data bucket gets created. Initially, the data bucket is empty, as indicated by the Item Count of 0 in Figure 16.

New Data Bucket wlslog
Figure 16: New Data Bucket wlslog

Adding Documents

To add documents, click Documents for the data bucket, as shown in Figure 17.

Figure 17: wlslog>Documents

Click Create Document to add a document, as shown in Figure 18.

Create Document
Figure 18: Create Document

In the Create Document dialog, specify a Document ID and click Create, as shown in Figure 19.

Create Document>Create
Figure 19: Create Document>Create

A new document gets added with some default fields, as shown in Figure 20.

New Document log1
Figure 20: New Document log1

Copy and paste the following JSON document to the log1 document:

   "Server state changed to STANDBY" }

Click Save to save the document, as shown in Figure 21.

Figure 21: wlslog>Documents>log1>Save

The log1 document gets formatted and gets added, as shown in Figure 22.

Document log1
Figure 22: Document log1

The log1 document gets listed in Documents for the wlslog data bucket, as shown in Figure 23.

Document log1
Figure 23: Document log1

Similarly, add another Couchbase document with Document ID “log2” with the following document JSON:

   "Server started in RUNNING mode" }

The log2 document also gets added to the wlslog data bucket, as shown in Figure 24.

Document log2
Figure 24: Document log2

The wlslog data bucket should list the Item Count as 2, as shown in Figure 25.

The wlslog Bucket with Item Count as 2
Figure 25: The wlslog Bucket with Item Count as 2

Accessing Server Logs

The server logs may be accessed from the Logs tab, as shown in Figure 26.

Server logs
Figure 26: Server logs


In this tutorial, we discussed using Couchbase Server on AWS including, creating a AWS EC2 instance, connecting with the instance, configuring the first node, accessing the Web console, creating a data bucket, and adding documents.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories