Menu
Article

Setup Couchbase Server and Sync Gateway on Ubuntu

Jaspalsinh Chauhan

Jaspalsinh Chauhan

• 4 min read

To start using Couchbase solution as data store for your mobile application you need to setup up couple of things.

This stack is named Couchbase Mobile and consist of three components:

  • Couchbase Lite (Embedded NoSQL database)
  • Couchbase Sync Gateway (Server component to synchronize data between the device and server)
  • Couchbase Server (NoSQL database server)

Download the above components from here.

Going forward we are going to setup the two server components from the above list on Ubuntu machine (Ubuntu 14.04 at the time of writing).

For the sake of writing, I have used droplet from Digital Ocean. But it is not restricted to any hosting provider. You can spin up a Ubuntu machine on Amazon Web Service, Microsoft Azure or any other hosting provider of your choice.

AWS also provides a ready made package for the same in AWS marketplace you can use.

Once you have a Ubuntu machine spawned - log into that machine via SSH, make sure you have all the updates installed (though not a compulsory thing).

sudo apt-get update
sudo apt-get upgrade

Step: Next thing you need to do is download Couchbase Server and Sync Gateway
Note: I am using community edition but same can used for Enterprise edition also, only download links must be changed.

Download Couchbase Server (Release at the time of writing: v4.1.0):

wget http://packages.couchbase.com/releases/4.1.0/couchbase-server-community_4.1.0-ubuntu14.04_amd64.deb

Download Couchbase Sync Gateway Component (Release at the time of writing: v1.3.1)

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/1.3.1/couchbase-sync-gateway-community_1.3.1-16_x86_64.deb

Note the download links used. If you are not using correct links you may end up getting an error while installing similar to the following:

dpkg-deb: error: 'couchbase-sync-gateway-community_1.3.1-16_x86_64.deb' is not a debian format archive
dpkg: error processing archive couchbase-sync-gateway-community_1.3.1-16_x86_64.deb (--install): 
subprocess dpkg-deb --control returned error exit status 2
Errors were encountered while processing:
couchbase-sync-gateway-community_1.3.1-16_x86_64.deb

Step: Install server components

Install Couchbase Server:

sudo dpkg -i couchbase-server-community_4.1.0-ubuntu14.04_amd64.deb

Install Couchbase Sync Gateway Component:

sudo dpkg -i couchbase-sync-gateway-community_1.3.1-16_x86_64.deb

Once above two components are install successfully, they will start running automatically and will start on machine start. These are also available to be referenced as service to control.

To start and stop Couchbase Server:

sudo service couchbase-server start
sudo service couchbase-server stop

To start and stop Couchbase Sync Gateway:

sudo service sync_gateway start
sudo service sync_gateway stop

Note: Sync Gateway is installed using following script for reference

Step: You can first time setup your Couchbase Server by opening following URL in your browser:

http://[your-machine-domain-name or IPAddress]:8091/

Step: Sync Gateway component when running provides two API:

  1. Sync Gateway Public API (Which will be consumed by clients via REST or by Couchbase Lite - Sync mechanism for push / pull replication). This is by default available on following URL: http://[your-machine-domain-name or IPAddress]:4984/mydb (where mydb is sample database)

  2. Sync Gateway Admin API (Which can be used by the admin or your server application for authentication / authorization and other administrative tasks. This is by default available on following URL: http://[your-machine-domain-name or IPAddress]:4985/mydb (where mydb is sample database)

By default sync gateway will run on localhost only so it would not be accessible from public address / port. When Sync Gateway starts if no configuration is provided it would pickup default configuration.

You can see the default configuration file, data (for in-memory walrus DB) and logs from sync_gateway activities by navigating to following location on your machine:

cd /home/sync_gateway/

If you want to change the configuration or use different configuration for the sync_gateway to use then update sync_gateway.json file at above mentioned location.

Here is a sample configuration you can use to check if the sync_gateway works fine or not:

{
  "interface": "0.0.0.0:4984",
  "adminInterface": "0.0.0.0:4985",
  "log": ["CRUD+", "REST+", "Changes+", "Attach+"],
  "pretty": true,
  "databases": {
    "mydb": {
      "server": "http://localhost:8091",
      "bucket": "default",
      "users": {
        "GUEST": {"disabled": false }
      },
      "sync":
        `function(doc, oldDoc) {
          channel(doc.channels);
      }`
    }
  }
}

Note: Few things to note here

  • Installing and setting up Couchbase Server and Sync Gateway as root user is not a good practice. Instead try to create another admin user on the same system. SSH using that user and follow the above step to setup your Couchbase Server Components.
  • 0.0.0.0 IP Address is used for the demo, you are not suppose to expose the sync_gateway admin API on public IPAddress / Port.
  • interface is the ref (1) Public API IPAddress / Port. adminInterface is the ref (2) Admin API IPAddress / Port.
  • mydb is the public fragment to use to connect with your database / bucket.
  • Here I am using default bucket created when I configured the Couchbase Server.
  • I have enabled GUEST user access, it means there is no restriction on accessing the sync_gateway public API.
  • sync function is default function in place and can be changed as per your application needs.

More info:

When we talk about Couchbase Mobile - this mean NoSQL embedded database on the client and full-blown Couchbase NoSQL database on server and a middle-ware layer that manages the syncing of data between the client and the server. This is the combo to use for an online / offline application solution.

Clients are not restricted to all three components, if they only want a local NoSQL database they can use Couchbase Lite alone without the server components.

Happy Coding!

Share