Rafael Ugolini is a full stack software developer currently based in Brussels, Belgium. He has been working with software development for more than 10 years and is lately focused on designing web solutions and developing using Python and JavaScript. Rafael Ugolini is Senior Software Developer at Famoco.



Docker is a great project that is helping developers around the world run applications in containers. This not only helps shipping software faster, but it also results with the famous “it works in my machine” phrase. In this article I will explain how to create a modular Couchbase image that doesn’t require any Web UI interaction to have a ready-to-go database for you.

All the code is available online here.


The first step is to create the Dockerfile.

Couchbase Version

This example is based on Couchbase Server Enterprise 4.6.1, but you can feel free to change to the specific version you are running in your environment.

Memory Configuration

All the values here are in MB:

– MEMORY_QUOTA: per node data service ram quota

– INDEX_MEMORY_QUOTA: per node index service ram quota

– FTS_MEMORY_QUOTA: per node index service ram quota


These are the services that will be available for the node created:

– kv: Data

– n1ql: Query

– index: Index

– fts: Full-Text Search


Username and password to be used in Couchbase Server.

Cluster Options

These options are only used if you want to add more than one node in the cluster.

– CLUSTER_HOST: hostname of the cluster for this node to join

– CLUSTER_REBALANCE: set “true” if you want the cluster to rebalance after the node is joined


The Couchbase Server image already ships with an entrypoint.sh script and we don’t want to override it. The trick here is to copy our version of entrypoint.sh to /config-entrypoint.sh, run Couchbase Server entrypoint.sh in the background, and after configuring the node attach the script back to the original ENTRYPOINT.


The ENTRYPOINT is used in combination with the original script from the Couchbase Server image. Let’s go line by line to understand how it works.

Initialize Couchbase Server

First we use set -m to enable job control, process running in background (like the original ENTRYPOINT) run in a separate process group. This option is turned off by default in non-interactive mode, like scripts.

Util Functions

This function is used to check when Couchbase Server starts answering HTTP calls.

This is just a util function, add a number before any echo in the script to count the steps taken automatically.

In order to parse the output of the nodes in Couchbase Server API, I’m using a function which runs ython to read STDIN, transform it to JSON and the Couchbase nodes. This is used for rebalancing.

Configure the Node

The first step is to wait until the server is ready, then using the function numbered_echo you can see how long it took for Couchbase Server to have the API calls available.

Then we set a variable HOSTNAME to be used in all the API calls we do and we also reset the counter from numbered_echo by setting it to 1.


First thing to do is to set up disk storage configuration and then we set the hostname.

Joining a Cluster

If CLUSTER_HOST is set, the script will try to add the current container to the cluster.

After adding the node into the cluster, the script can also check for the variable CLUSTER_REBALANCE to see if it needs to rebalance the cluster automatically. This is where we use the Python function to read the nodes from /pools/default endpoint.

Not joining a cluster

Memory settings for the services.

Services to be used by the node.

Set up the credentials for the node.


To end the script, we attach it to the original ENTRYPOINT.


To demonstrate how to use it, I will be using the image registered in Docker Hub with the code here.

Single node


This runs a single node using the minimum required memory and the default credentials (Administrator/password) registered in the image. All the network ports Couchbase Server uses are exposed as well.

The command above plays a little with the environment variables available in the Dockerfile.


In this example, we will connect 3 nodes in the cluster.


We must first create a network Couchbase where we will connect all nodes.

Then we create the first node.


Since all the network ports are exposed in the first node, it’s not necessary to expose them here.

Attention to the detail that CLUSTER_HOST is set to node1.cluster which is the hostname of the first node and CLUSTER_REBALANCE is also set to true. Once the node is added to the cluster, it will rebalance automatically.


The node3 is also added to the cluster, but since CLUSTER_REBALANCE wasn’t set, it will require manual rebalance of the cluster for it to become available.


This post is part of the Couchbase Community Writing Program


Posted by Laura Czajkowski, Developer Community Manager, Couchbase

Laura Czajkowski is the Snr. Developer Community Manager at Couchbase overseeing the community. She’s responsible for our monthly developer newsletter.

Leave a reply