Docker is becoming increasingly popular and I’ve been slowly introducing it into my projects.  It makes it easy to distribute your applications because regardless of where you deploy your containers to, the experience will be the same. Let’s see how this works using Docker and Node.js, which has many variations. While they generally work regardless of the web application scenario, you can’t truly be sure when using the Node.js runtime.

We’re going to see how to build a custom NoSQL container and deploy it alongside a custom web application container that makes use of Node and Docker to encapsulate the needed Couchbase functions.

What is Node.js?

Before we get to the tutorial, let’s spend a minute defining Node.js. Instead of running inside a browser, Node is an open source and fully cross-platform runtime for executing JavaScript in a server environment. With Node.js, developers can create fully cloud applications that operate invisibly to users but which provide crucial functionality in modern enterprises. Couchbase is optimized to execute applications built with Node.js. This tutorial demonstrates how to harness this capability by pairing Node.js and Docker containers.

If this is your first time being exposed to Docker containers, let’s break down what we’re hoping to accomplish.  Couchbase has published an official Docker image to Docker Hub for Node.js developers, but the image is not pre-provisioned.  That is not a bad thing and it is definitely what we would hope to expect in a database container.  This means that we need to create a custom image based on the official image, otherwise when we deploy Couchbase, it won’t have been set up.  We’re going to write an application in Node.js and “Dockerize” it into a container package.  These two Couchbase and Node.js Docker containers will be able to communicate with each other.

Creating a Custom Couchbase Server Docker Image and Container

Create a directory somewhere on your computer and include the following two files:

The sample dockerfile — Dockerfile — will represent our custom image, and the file will be a runtime script for when we deploy our container.

Open the Dockerfile file and include the following:

Our custom image will use the official Couchbase image as the base.  At build time, the configuration script will be copied to the image.  When run, the script will be executed.  Let’s take a look at that script.

Open the file and include the following:

Again, the point of the script is to provision the server after it is launched.  To do this, we can make use of the Couchbase RESTful API.  Configuration includes creating a cluster, enabling Couchbase services, defining administration credentials, creating a Bucket, and creating a N1QL index on the bucket.

In the configuration script you’ll notice several environment variables being used, for example the $COUCHBASE_ADMINISTRATOR_USERNAME variable.  This will save us from hard-coding potentially sensitive information into the image.  Instead we can define these variables at deployment.

Now let’s build the custom Couchbase image for our project.  From the Docker Shell, execute the following:

In the above command, the couchbase-custom text is the name of our image, while the path is the path to our Dockerfile and files.

With the custom image created for Couchbase, execute the following command to run it:

The above command says we want to deploy a container, mapping each of the necessary Couchbase ports.  We pass in the environment variables that are found in our script and we define which network we want the container to run on.  The container will be named couchbase, which is also going to be the container’s host name.

Creating a Node.js RESTful API Web Application

With Couchbase up and running, we can develop a simple Node.js application.  Create a directory somewhere on your computer to represent our project.  Within that project, create an app.js file.  We’re going to be installing private packages with NPM in a Docker container. From the Command Prompt or Terminal, execute the following:

The above command will create a very basic package.json file which will be the foundation of our Node.js application.  There are a few dependencies that must be installed, so let’s execute the following to obtain them:

We’ll be using express for building our API, couchbase as our SDK, body-parser for working with POST bodies, and uuid for generating unique id values that will represent document keys.

With the application foundation in place, we can start developing the application.  Open the project’s app.js file and include the following code:

So what is happening in the above code?

First we import all the downloaded dependencies and then we establish a connection to Couchbase.  You’ll notice that we are using process.env throughout the code.  This allows us to read environment variables.  We’re going to be using a similar approach to what we saw in the Couchbase image.

The API has two endpoints that actually do anything.  The /save endpoint will insert whatever is in the request body and the /get endpoint will query for whatever is saved in Couchbase.

Containerizing the Node.js Web Application

With the application built, we need to containerize it so it can be deployed easily with Docker.  In the same directory as your package.json file, add the following two files:

The plan is to create a custom image based on the official Node.js Docker image.  Within the Dockerfile file, include the following:

During the image build time, we are going to copy our project into the image filesystem and change the working directory.  Then we are going to install all the dependencies found in the package.json file.  When the container is deployed, the app.js file will be ran.

You might be wondering why we are doing an install when we build the image.  We are doing this because we don’t want to copy the dependencies into the image as there could be OS and architecture incompatibilities.  To exclude the node_modules directory from our image, include the following in the .dockerignore file:

Anything you want excluded from the image can go in that file.

To build this image, execute the following from the Docker Shell:

The image name for our Node.js application will be called nodejs-custom and it will be based on the directory that contains the Dockerfile file.  More information on building custom Docker images can be found in a previous article that I wrote.

With the image available, we need to run it.  From the Docker Shell, execute the following:

The above command should look familiar to what we saw in the Couchbase deployment.  We are defining the port mapping of our application, passing in the environment variables that are used in the app.js file, defining the container network and the image name.

If you go to your web browser and navigate to any of the endpoints of the web application, it should work fine.

Using a Compose File for Deploying Docker Containers

Having to remember all the environment variables and everything in the command for deploying the containers can be painful.  Creating a Compose file can make things a lot simpler.

After you’ve created your two custom images, create a docker-compose.yml file somewhere on your computer.  This file should contain the following:

When using Compose, you don’t have to worry about defining the network as everything in the file will be on the same network.  To launch either of the containers, you can execute the following:

With Couchbase, you can’t spin everything up together because Couchbase doesn’t have a method of telling you when it is ready.  Because of this, the Node.js application might try to connect before Couchbase is ready to accept connections.

The above command usually spins up all containers in the Compose file, but we can’t use it in this scenario.


If you’re wondering how you can deploy your Node.js with Couchbase web application, Docker is an easy solution.  After building images of either Couchbase or Node.js, you can trust that it will work the same on any server or computer running the Docker Engine.

For more information on using the Couchbase Node.js SDK, check out the Couchbase Developer Portal.


Posted by Nic Raboy, Developer Advocate, Couchbase

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in Java, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Apache Cordova. Nic writes about his development experiences related to making web and mobile development easier to understand.


  1. […] too long ago I wrote about containerizing a Node.js RESTful API and Couchbase Server to demonstrate how easy it is to deploy web applications in a quick and reliable fashion.  In that […]

  2. […] If you’re interested in deploying a containerized Node.js web application that uses Couchbase containers, check out this article that I had previously written called, Deploy a Node.js with Couchbase Web Application as Docker Containers. […]

Leave a reply