Getting Started with Couchbase: Installation and Setup Guide

Image by Editor (Kanwal Mehreen) | Canva

Couchbase is a distributed NoSQL document-oriented database designed for interactive applications. It can be installed on Windows, macOS, and Linux, and it can also run in Docker if you prefer using containers. Once installed, Couchbase provides a web-based user interface to simplify the setup process, allowing you to create and manage your data clusters and buckets. This article will help you get started with Couchbase.

# Prerequisites

Before starting the installation, make sure your system meets these requirements:

Operating System: Couchbase Server can run on Windows, macOS, and Linux
Hardware Requirements: At least 4 GB of RAM for testing, 8 GB or more for production, and a multi-core CPU
Disk Space: At least 10 GB for Couchbase storage and indexes
Network: Access to ports such as 8091 for the Couchbase Web Console and other service ports like 11210 for data

Docker can also be used to run Couchbase for easier installation and isolation. For production environments, you’ll also need to manage Couchbase clusters across multiple nodes.

# Downloading Couchbase

To get started, download the Couchbase Server package for your operating system:

Go to the Couchbase Downloads Page
Choose the appropriate version and platform (Windows, macOS, or Linux)
Download the installation package

# Installing Couchbase Server

// Windows Installation

Run the downloaded .exe file
Follow the on-screen instructions to complete the installation
Once installed, the Couchbase Server will start automatically

// macOS Installation

Open the downloaded .dmg file
Drag the Couchbase Server icon into the Applications folder
Launch Couchbase Server from Applications

// Linux Installation

For Debian/Ubuntu systems, use the following commands:

sudo dpkg -i couchbase-server-enterprise_version.deb
sudo systemctl start couchbase-server

// Docker Installation

Couchbase Server can also be deployed as a Docker container:

docker run -d --name couchbase -p 8091-8094:8091-8094 -p 11210:11210 couchbase:latest

For more configurations, visit the official Couchbase Docker documentation.

# Setting Up the Couchbase Web Console

After installing Couchbase Server, you can use the Couchbase Web Console to manage and monitor your instance.

Open a web browser
Navigate to http://localhost:8091, which is the default port
The setup wizard will guide you through the initial configuration steps

# Creating a Cluster

The Couchbase Server requires at least one cluster for organizing data. During the setup process:

Choose “Create a New Cluster”
Name your cluster (e.g., MyCouchbaseCluster)
Set a password for the Couchbase Admin account
Allocate available resources (RAM) for your cluster services

# Adding a Bucket

A bucket is a logical grouping of data, similar to a database or a collection. To create a new bucket:

In the Couchbase Web Console, go to the Buckets tab
Enter a name for the bucket (e.g., UserData)
Allocate memory to the bucket and configure other settings like replicas and eviction policies
Click Add Bucket to create it

Buckets are Couchbase’s core units of storage and can be used to separate data by use case or application component.

# Basic Configuration and Optimization

After setting up the cluster and bucket, optimize the configuration for better performance:

Memory Quota: Adjust memory allocation for Data, Index, and Query services based on workload requirements
Auto-Failover: Enable automatic failover to recover from node failures quickly
Indexing: Choose memory-optimized indexes for frequently queried data

# Connecting to Couchbase via SDKs

Couchbase provides Software Development Kits (SDKs) for multiple programming languages, including Java, Python, Node.js, and .NET. To connect to Couchbase from your application:

Install the Couchbase SDK for your language. For example, in Node.js:

Connect to your cluster and perform CRUD (Create, Read, Update, Delete) operations. Here is a basic example:

async function run() {
    // Insert a document
    await collection.upsert("user::123", { name: "John Doe", age: 29 });

    // Retrieve the document
    const result = await collection.get("user::123");
    console.log("User:", result.content);
}

run().catch((err) => console.error("Error:", err));

Each SDK has its own detailed documentation for deeper functionality, which you can find on the Couchbase SDK page.

# Using the Couchbase Command Line Interface

Couchbase also includes a Command Line Interface (CLI) for managing clusters. The general syntax of a couchbase-cli command is as follows:

couchbase-cli  -c : -u  -p  [options]

# Common Couchbase CLI Commands

Here are some of the most commonly used commands:

Cluster Initialization: Initializes a new Couchbase cluster

couchbase-cli cluster-init -c localhost:8091 -u Administrator -p password 
    --cluster-username Administrator --cluster-password password 
    --services data,index,query

Bucket Creation: Creates a new bucket for storing data

couchbase-cli bucket-create -c localhost:8091 -u Administrator -p password 
    --bucket testBucket --bucket-type couchbase --bucket-ramsize 100

Adding a Node: Adds a new node to the cluster

couchbase-cli server-add -c localhost:8091 -u Administrator -p password 
    --server-add  --server-add-username Administrator 
    --server-add-password password

Rebalancing the Cluster: Rebalances the cluster after adding or removing nodes

couchbase-cli rebalance -c localhost:8091 -u Administrator -p password

# Verifying the Setup

To verify that your Couchbase Server setup is working:

Web Console: Check the Couchbase Web Console for the health of your cluster and buckets
Metrics: Monitor server and cluster health using the built-in metrics in Couchbase
Sample Query: Run a sample query using N1QL in the Query Editor tab of the Web Console

# Conclusion

Couchbase is a powerful NoSQL database built for modern applications. Its straightforward installation on Windows, macOS, Linux, and Docker allows for quick setup. The web console simplifies management, while clusters and buckets provide robust data organization. By tuning memory and indexing settings, you can optimize performance for speed and efficiency. Furthermore, Couchbase’s SDKs allow for seamless integration with various programming languages, and the CLI provides a robust toolset for command-line management.

Jayita Gulati is a machine learning enthusiast and technical writer driven by her passion for building machine learning models. She holds a Master’s degree in Computer Science from the University of Liverpool.