Container technologies such as Docker have vastly simplified the software development, test and deployment process by allowing you to package applications along with their complete runtime environment that abstract away differences in infrastructure and OSes. This post is a primer on how you can use Docker to set up your Couchbase Mobile environment and some troubleshooting tips.

Everything discussed here applies to a typical development environment with the goal of expediting the development process so you can quickly and easily start building mobile apps using Couchbase Mobile.

In a future post, we will discuss how you can leverage orchestration technologies such as Kubernetes to scale out and manage the deployment of Couchbase Mobile cluster in production environments.

Background

At a high level, the full Couchbase Mobile stack comprises of the following components:
– The Couchbase Lite which is the NoSQL embedded database integrated into your mobile apps
– The Sync Gateway which is responsible for data synchronization across the clients and Couchbase Server
– The Couchbase Server which is responsible for data persistence

To get started with development using Couchbase Mobile, you need an instance of Couchbase Server and Sync Gateway. I refer to these components as the “Couchbase Mobile Backend”. You will integrate the Couchbase Lite framework into your apps.

In this post, we will learn how to use Docker to deploy a single instance of a Sync Gateway 1.5 and a single node cluster of the Couchbase Server 5.0 on a desktop environment suited for development purposes.

Installing Docker

If you haven’t done so already, please install Docker per the install guide for your desktop environment.

You can verify your docker install by typing the following command in a terminal window.

You should see a response similar to below

Installing Latest Couchbase Server

Couchbase Server is available on Docker Hub in the couchbase repo. At time of writing this post, this version is 5.0.1.

  • You will first get the docker image from Docker Hub. Open a new terminal window and run the following. This will pull the Enterprise version of Couchbase server.  The Enterprise version is free to use for development purposes.  The Community version is also available on Docker Hub.

  • Create a local docker network named “cbnetwork” if one does not exist already. Open a terminal window and run the following two commands

Configuring Couchbase Server

Once your Couchbase Server is up and running, you will have to configure it before you can start using it with your Sync Gateway

Here are the minimal set of the things you will have to do :-

  • Create a cluster with appropriate services. A single node cluster is sufficient for development needs
  • Configure Adminstrator Account
  • Create a default bucket
  • Create a RBAC user with bucket access. The RBAC user credentials is used by the Sync Gateway to talk to the Couchbase Server

You have two options on how to configure the Couchbase Server – Manual and Automated. Jump to the appropriate section depending on your choice.

Option 1: Manual Configuration using the Admin UI

You can configure the Couchbase Server via the Couchbase Admin Console UI
In order access the Admin UI, we must run the docker image that we pulled earlier.

  • Run Couchbase Server with the following command. This runs the Couchbase Server as a daemon process.

  • You can view the logs at any time by running the following command

  • If your server has succesfully launched, you should see something like this in your output

  • It may take a few seconds for the server to startup. Verify that the docker image is running with following command

  • Once the server is up and running, access it by opening the URL http://localhost:8091 in your browser
  • Follow the instructions in the setup guide to configure the Administrator account and to create a single node cluster
  • Follow the intructions here to create a bucket
  • The instructions here discuss how you can configure a RBAC user for your bucket
  • Once your server is setup, be sure to make note of
    • The name of the bucket that you created
    • The RBAC user credentials that you used for setup

The RBAC credentials and name of bucket will be required when you are ready to configure your Sync Gateway appropriately

The manual process is fine but can get tedious if you have to repeat this process a number of times on each of your development setups. Wouldn’t it be great if the configuration steps could be automated. If you are interested in learning about that, proceed to the next section , else just skip ahead to the section on setting up the Sync Gateway.

Option 2: Automating the Configuration Process

I have generated a custom docker image from the Couchbase Server 5.0.1 Enterprise image that will allow you to launch the container with appropriate configuration values via the command line.

If you want to generate your own custom image from the Community edition, then follow the steps in the “Building your own custom configurable docker image” section in this post.

  • Download this custom development version of the Couchbase Server image based on Enterprise Couchbase Server 5.0.1

  • Once you have succesfully downloaded the custom image, you can launch it by providing it with the appropriate configuration values as part of the launch command. Make sure you record the RBAC user credentials and name of bucket. These will be relevant during Sync Gateway configuration
    • COUCHBASE_ADMINISTRATOR_USERNAME is the name of Couchbase Admin Administrator
    • COUCHBASE_ADMINISTRATOR_PASSWORD is Couchbase Admin Administrator password
    • COUCHBASE_BUCKET is the database bucket that you would like to create
    • COUCHBASE_RBAC_USERNAME is the name of the RBAC user with full bucket access
    • COUCHBASE_RBAC_PASSWORD is the password of the RBAC user
    • COUCHBASE_RBAC_NAME is a user friendly name for the RBAC user
    • CLUSTER_NAME the name of the cluster

    Open a terminal window and type the following command. You can provide suitable values for each of the configurable parameters.

  • You can view the logs at any time by running the following command

  • That’s it! Now you can test out your installation. Access it by opening the URL http://localhost:8091 in your browser and verify that your configuration is as specified

Building your own custom configurable docker image

If you are wondering how we generated the custom image, you can check out the steps specified in this guide. We took the approach inspired by the tutorial. We built a custom docker image from the base Coucbase Enterprise server image that is configured for our development needs. You can build a similar custom image from the Community image of Couchbase server .

There are a tonne of custom configurable values as described in the Couchbase CLI and REST interface specs. We specified a few important ones and left the others to defaults.

If you would like to generate your own image based on a different version of Couchbase Server and/or if you would like to customize the configurable parameters, you can update the configuration script used in the guide .

Installing Couchbase Sync Gateway 1.5

Now that you have the Couchbase Server configured and up and running, we will install the Sync Gateway. It is important that the Couchbase Server is up and running before you get started with the Sync Gateway.

The Sync Gateway is available on Docker Hub in the couchbase repo.

  • You will first get the docker image from Docker Hub. Open a new terminal window and run the following.

  • The Sync Gateway must be launched with a configuration file where you specify among other things, the URL of the Couchbase Server to connect to, the bucket to access and the RBAC credentials to use for bucket access. The config file determines that runtime behavior of the sync gateway.

The docker image that you pulled is built with a default configuration file. If you specify none, that’s what will be used (and that’s probably not going to work for you).

  • If you have a configuration that you would like to use, open it in an editor of your choice. If not, create a new config file named sync-gateway-config.json and copy the following configuration setup.

You can add an appropriate sync function or any of the other configuration properties. We will focus on the key ones that are essential for our development environment. You should make appropriate edits to the config file as specified below.

  • The server URL specifies the name of the Couchbase Server container. In the docker run command used to launch the Couchbase Server, we specified the name using the --name option.
  • The database and bucket must correspond to the $COUCHBASE_BUCKET value that you used when you configured the Couchbase Server. In our example, that was specified to be demobucket.
  • The username corresponds to the username of the RBAC account that you created for bucket access as specifed by the $COUCHBASE_RBAC_USERNAME value that you used for when you configured the Couchbase Server. In our example, that was specified to be admin.
  • The password corresponds to the password of the RBAC account that you created for bucket access as specifed by the $COUCHBASE_RBAC_PASSWORD value that you used for when you configured the Couchbase Server. In our example, that was specified to bepassword`.
  • Once the configuration file is setup, you will launch the Sync Gateway with the file. For this, open a terminal and run the following commmands

  • You can view the logs at any time by running the following command

  • It may take a few seconds for the sync gateway to startup. Verify that the docker image is running with following command

  • Verify that your sync gateway is running by opening the URL http://localhost:4984 in your browser
    You should see the following output

  • Verify that the sync gateway is talking to the Couchbase Server bucket by opening the URL http://localhost:4985/demobucket/ in your browser. Here demobucket is the name of the database bucket that we created.
    You should see output similar to one below indicating the version of sync gateway

That’s it! You have your docker instance of sync gateway talking to the Couchbase Server

Troubleshooting Tips

Stopping/ Starting Containers

  • You can stop and restart the docker containers at any point using the stop and start docker commands as follows.
    • Stopping Containers

    • Starting Containers

Note that if you stop the Couchbase Server, the Sync Gateway will attempt to reconnect with the server for a few minutes before giving up. So if the server is stopped for an extended period of time, you will need to stop and restart the Sync Gateway container as well or use the _online API to bring it back online again.

Updating Sync Gatway Configuration

  • If you want to update the sync gateway configuration, you will need to re-run the Sync Gateway with an updated sync gateway config file. For this, you will need to stop and remove the sync gateway container.

If you do not remove the sync-gateway image , you will see a “name conflict error” similar to one below if you try to start the sync-gateway again with updated config.

Updating Couchbase Server Configuration

  • Similarly, if you want to re-run the Couchbase server with an updated configuration, you will need to stop and remove the couchbase server.

However, depending on the server configuration that is changed, you may also need to stop and remove sync gateway container and relaunch it with updated sync gateway config file. For instance, if you changed the RBAC credentials for the bucket or if you changed the name of the bucket that.

Running commands in the container

Sometimes, you may want to run commands directly on the running container. For this you can use the docker exec command to open up a shell into the container. This is extremely useful for debugging and such. You will need root privileges to be able to run the command.

  • couchbase server
  • sync gateway

What Next

As you probably gathered from this post, docker containers make it extremely convenient to get you up and going with a custom “Couchbase Mobile backend” on your development environment. With the backend setup out of the way, you can focus on building your awesome mobile apps with Couchbase Lite.

While we discussed setting up docker containers in a desktop environment, we will explore cloud deployment options in a future post, so stay tuned.

If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me priya.rajagopal@couchbase.com.  The Couchbase Forums are another good place to reach out with questions.

Finally, thanks to Traun Leyden, for his feedback on this post.

 

Posted by Priya Rajagopal , Principal Product Manager

Priya Rajagopal is a Principal Product Manager for Couchbase focusing on the Couchbase Mobile platform. She has been professionally developing software for over 19 years with the last 7 years on mobile technologies. She has spent a decade in software R&D and is a co-inventor on 22 technology related patents.

Leave a reply