Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Getting Started With Couchbase Mobile Using Docker Containers

DZone's Guide to

Getting Started With Couchbase Mobile Using Docker Containers

Learn how you can leverage orchestration technologies like Kubernetes to scale out and manage Couchbase Mobile clusters in production.

· Mobile Zone ·
Free Resource

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.

    docker --version

You should see a response similar to below:

    Docker version 17.09.0-ce, build afdb6d4

Installing the Latest Couchbase Server

Couchbase Server is available on Docker Hub in the couchbase repo. At the 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.
    docker pull couchbase
  • Create a local docker network named “cbnetwork” if one does not exist already. Open a terminal window and run the following two commands
   docker network ls
   docker network create -d bridge cbnetwork

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 Administrator Account.
  • Create a default bucket.
  • Create an RBAC user with bucket access. The RBAC user credentials are 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.
docker run -d --name cb-server --network cbnetwork -p 8091-8094:8091-8094 -p 11210:11210 couchbase/server
  • You can view the logs at any time by running the following command:
    docker logs -f cb-server
  • If your server has successfully launched, you should see something like this in your output:
Starting Couchbase Server -- Web UI available at http://<ip>:8091 and logs available in /opt/couchbase/var/lib/couchbase/logs
  • It may take a few seconds for the server to startup. Verify that the docker image is running with the following command:
    docker ps
  • 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 instructions here to create a bucket.
  • The instructions here discuss how you can configure an RBAC user for your bucket.
  • Once your server is set up, 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 the 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; otherwise, 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:
    docker pull priyacouch/couchbase-dev

Once you have successfully 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 the name of the 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.

$ docker run -d --name cb-server --network cbnetwork -p 8091-8094:8091-8094 -p 11210:11210 -e COUCHBASE_ADMINISTRATOR_USERNAME=Administrator -e COUCHBASE_ADMINISTRATOR_PASSWORD=password -e COUCHBASE_BUCKET=demobucket -e COUCHBASE_RBAC_USERNAME=admin -e COUCHBASE_RBAC_PASSWORD=password -e COUCHBASE_RBAC_NAME="admin-user" -e CLUSTER_NAME=demo-cluster couchbase-dev
  • You can view the logs at any time by running the following command:
docker logs -f cb-server
  • 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:

Image title

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 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 is a ton 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.
    docker pull couchbase/sync-gateway


  • 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:
{
  "interface":":4984",
  "log": ["sync"],
  "databases": {
    "demobucket": {
      "import_docs": "continuous",
      "unsupported": {
        "enable_extended_attributes": true,
        "replicator_2":true
      },
      "bucket":"demobucket",
      "server": "http://cb-server:8091",
      "enable_shared_bucket_access":true,
      "username": "admin",
      "password": "password",
      "users":{
          "admin": {"password": "password", "admin_channels": ["*"]}
      }
   }
}
}

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 as 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 set up, you will launch the Sync Gateway with the file. For this, open a terminal and run the following commands:
    cd /path/to/sync-gateway-config.json

    docker run -p 4984-4985:4984-4985 --network cbnetwork --name sync-gateway -d -v `pwd`/sync-gateway-config.json:/etc/sync_gateway/sync_gateway.json couchbase/sync-gateway -adminInterface :4985 /etc/sync_gateway/sync_gateway.json
  • You can view the logs at any time by running the following command:
    docker logs -f sync-gateway


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


  • Verify that your sync gateway is running by opening the URL http://localhost:4984in your browser. You should see the following output:
   {"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":1.5},"version":"Couchbase Sync Gateway/1.5.0(594;e78dbf1)"}


  • 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:
{"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":1.5},"version":"Couchbase Sync Gateway/1.5.1(4;cb9522c)"}

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
    docker stop sync-gateway
    docker stop cb-server
  • Starting containers
    docker start cb-server
    docker start sync-gateway

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 API to bring it back online again.

Updating Sync Gateway 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.
   docker stop sync-gateway
   docker rm sync-gateway

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.

   docker: Error response from daemon: Conflict. The container name "/sync-gateway" is already in use by container "bc67153afda9b90303b2965b62c5e34751ce3748fd8d5fb7ed38a418d7b77cfd". You have to remove (or rename) that container to be able to reuse that name.

   See 'docker run --help'.

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.
   docker stop cb-server
   docker rm cb-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.

  • Ccouchbase server:

sudo docker exec -i -t cb-server /bin/bash
  • Sync gateway:

 sudo docker exec -i -t sync-gateway /bin/bash

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" in 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 at priya.rajagobal@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.

Topics:
mobile ,couchbase ,docker ,containers ,tutorial

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}