Background

Installing Docker

docker --version

Docker version 17.09.0-ce, build afdb6d4

Installing Latest Couchbase Server

• 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

• 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

Option 1: Manual Configuration using the Admin UI

• 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 succesfully 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 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 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

Option 2: Automating the Configuration Process

• 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 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.

$ 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

Building your own custom configurable docker image

Installing Couchbase Sync Gateway 1.5

• 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.

• 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": ["*"]}
      }
   }
}
}

• 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

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 following command

docker ps

• Verify that your sync gateway is running by opening the URL http://localhost:4984 in 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)"}

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 cb-server

  • Starting Containers

  docker start cb-server
      docker start sync-gateway

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.

docker stop sync-gateway
   docker rm sync-gateway

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

Running commands in the container

• couchbase server
  

  sudo docker exec -i -t cb-server /bin/bash

• sync gateway
  

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

What Next