©2015 -
Information Technology
COUCHBASE MOBILE SYNC GATEWAY
Sync Gateway Server is an application that provides a means to synchronize the data between Couchbase Lite and Couchbase Server. It runs an HTTP Listener to the replication endpoint and uses a Couchbase Server bucket as a persistent storage for the replicated documents.
This article is my quick implementation guide for Sync Gateway setup.
TABLE OF CONTENTS
Couchbase Sync Gateway Non-
Shell Environment Profile Setup
Sync Gateway Parameter Options
Sync Gateway Firewall Configuration
Create A Bucket For Sync Gateway
Starting Sync Gateway With A Configuration File
Couchbase Sync Gateway Root Installation
COUCHBASE SYNC GATEWAY NON-
The non-
At your designated Linux Gateway Server, create a directory for sync gateway software and to be owned by couchbase account
[root@lxnode4 ~]# mkdir -
[root@lxnode4 ~]# chown -
[root@lxnode4 ~]# ls -
drwxr-
[root@lxnode4 ~]#
Download the current release of Sync Gateway from Couchbase website:
http://www.couchbase.com/nosql-
The download contains an executable file called sync_gateway that you run as a command-
For convenience, you can place the file into a directory that is included in your $PATH environment variable.
Extract the Sync Gateway RPM into /app/couchbase/mobile directory.
[couchbas@lxnode4 ~]$ cd /app/couchbase/mobile
[couchbas@lxnode4 mobile]$ ls -
-
[couchbas@lxnode4 mobile]$ rpm2cpio $HOME/couchbase-
> -
35910 blocks
[couchbas@lxnode4 mobile]$
New directories are created for this installation and the sync gateway HOME path would be:
<mount point>/opt/couchbase-
[couchbas@lxnode4 mobile]$ ls
opt
[couchbas@lxnode4 mobile]$ cd opt
[couchbas@lxnode4 opt]$ ls
couchbase-
[couchbas@lxnode4 opt]$ cd couchbase-
[couchbas@lxnode4 couchbase-
bin examples LICENSE.txt manifest.txt manifest.xml README.txt service VERSION.txt
[couchbas@lxnode4 couchbase-
Shell Environment Profile Setup
For convenience, add the Sync Gateway bin path to your shell $PATH settings.
[couchbas@lxnode4 bin]$ pwd
/app/couchbase/mobile/opt/couchbase-
[couchbas@lxnode4 bin]$ cd
[couchbas@lxnode4 ~]$ vi .bash_profile
# .bash_profile
# Get the aliases and functions
if [ -
. ~/.bashrc
fi
# User specific environment and startup programs
PATH=$PATH:$HOME/bin
# Couchbase Sync Gateway
CBSG_HOME=/app/couchbase/mobile/opt/couchbase-
PATH=$CBSG_HOME/bin:$PATH:.
export PATH
Then, exit the shell and re-
[couchbas@lxnode4 ~]$ which sync_gateway
/app/couchbase/mobile/opt/couchbase-
[couchbas@lxnode4 ~]$
At this point, we have completed the installation of Sync Gateway.
Production Deployment and Scalability
Sync Gateway Parameter Options
The Sync Gateway has a single executable called sync_gateway. You would run this executable along with the parameters to start the Sync Gateway.
[couchbas@lxnode4 ~]$ sync_gateway -
Usage of sync_gateway:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
[couchbas@lxnode4 ~]$
Sync Gateway has a default light weight in-
sync_gateway. Unless specified by the parameter, the bucket sync_gateway has to exist in the Couchbase server.
Sync Gateway Firewall Port Configuration
In addition to the ports required to access the Couchbase server by a CBC or any SDK client (see article on network firewall ports), the following ports need to be opened to access the Sync Gateway. The firewall settings need to be applied on both the Linux server firewall and your network firewall.
4984 (public default port, tcp)
4985 (admin default port, tcp)
Example:
Based on the default configuration, you can access the status of sync gateway at http://127.0.0.1:4985
Create A Bucket For Sync Gateway
[couchbas@lxnode4 ~]$ cbc bucket-
> -
Requesting /pools/default/buckets
Bucket password:
202
Cache-
Content-
Date: Thu, 28 Jan 2016 19:20:17 GMT
Location: /pools/default/buckets/sync_gateway
Pragma: no-
Server: Couchbase Server
[couchbas@lxnode4 ~]$
Just to get started, let's create a simple configuration with a gateway database called guest_app.
config file: sg_config.json
{
"databases": {
"guest_app": {
"server":"http://lxnode5.vlabs.net:8091",
"bucket":"sync_gateway",
"users": { "GUEST": {"disabled":false, "admin_channels":["*"]}
}
}
}
}
For more details, see Couchbase Mobile Reference Guide
"databases":<{array}> This is an array of database properties.
For more details, see Couchbase Database Configuration Reference
"server":<string> Your Couchbase server (or Walrus) URL
"bucket":<string> The bucket for which the Sync Gateway will use as a data source
"password":<string> The bucket password for authenticating to Couchbase Server. There is no default.
"users":<{array}> List of Users to create along with their properties. There is no default.
"roles":<{array}> List of Roles to create along with their properties. There is no default.
Starting the Sync Gateway With A Configuration File
Syntax:
sync_gateway your_sg_config.json
[couchbas@lxnode4 ~]$ sync_gateway sg_config.json
2016-
2016-
2016-
2016-
2016-
2016/01/28 13:40:53 Trying with selected node 1
2016/01/28 13:40:53 Trying with http://172.16.33.88:8091/pools/default/bucketsStreaming/sync_gateway
2016/01/28 13:40:53 Got new configuration for bucket sync_gateway
2016/01/28 13:40:54 Trying with selected node 1
2016-
2016-
2016-
2016-
NOTE: To run the non-
Example:
[couchbas@lxnode4 ~]$ nohup ./sync_gateway sg_config.json &
To verify that the gateway is working correctly, use a browser or a curl utility to access the public URL to get the status of the guest_app database.
[couchbas@lxnode4 ~]$ curl http://localhost:4984/guest_app/
{"committed_update_seq":1,"compact_running":false,"db_name":"guest_app","disk_format_version":0,"instance_start_time":1454010054249677,"purge_seq":0,"update_seq":1}
[couchbas@lxnode4 ~]$
[couchbas@lxnode4 ~]$ curl http://lxnode4.vlabs.net:4984/guest_app/
{"committed_update_seq":1,"compact_running":false,"db_name":"guest_app","disk_format_version":0,"instance_start_time":1454010054249677,"purge_seq":0,"update_seq":1}
[couchbas@lxnode4 ~]$
The database status reply coming from the Sync Gateway proves that it is working.
Press Ctrl-
NOTE: For root installations, use the initctl to stop the service.
In our initial demonstration, our sync_gateway bucket is empty. But the moment you startup Sync Gateway, it would add metadata into any bucket you associate it to.
Thus it is important _not_ to point the sync gateway to an existing bucket that have data used by other applications.
Below shows the meta data contents of the sync_gateway bucket after the Sync Gateway was started.
Knowing that Sync Gateway adds its own metadata to the bucket source, Couchbase has provided a Bucket Shadowing feature that avoids adding the metadata into the original bucket that has already an existing data that was used also by other non-
Here's an example of a config file that uses CRUD_Lab bucket that has an existing data used previously by my lab exercises of my other articles.
I have added a new database called emp_app as our sample shadow bucket implementation.
File: sg_config2.json
{
"databases": {
"guest_app": {
"server":"http://lxnode5.vlabs.net:8091",
"bucket":"sync_gateway",
"users": { "GUEST": {"disabled":false, "admin_channels":["*"]}}
},
"emp_app": {
"server":"http://lxnode5.vlabs.net:8091",
"bucket":"syncGW_CRUD_Lab",
"shadow":{ "server":"http://lxnode5.vlabs.net:8091", "bucket":"CRUD_Lab" },
"users": { "GUEST": {"disabled":false, "admin_channels":["*"]}}
}
}
}
Create a new bucket for the Sync Gateway,
[couchbas@lxnode4 ~]$ cbc bucket-
> -
Requesting /pools/default/buckets
Bucket password:
202
Cache-
Content-
Date: Mon, 01 Feb 2016 20:17:00 GMT
Location: /pools/default/buckets/syncGW_CRUD_Lab
Pragma: no-
Server: Couchbase Server
[couchbas@lxnode4 ~]$
Start the Sync Gateway with the new config file,
sync_gateway sg_config2.json
[couchbas@lxnode4 ~]$ sync_gateway sg_config2.json
2016-
2016-
2016-
2016-
2016-
2016/02/01 14:28:01 Trying with http://172.16.33.88:8091/pools/default/bucketsStreaming/sync_gateway
2016/02/01 14:28:01 Trying with selected node 1
2016/02/01 14:28:01 Got new configuration for bucket sync_gateway
2016/02/01 14:28:01 Trying with selected node 1
2016-
2016-
2016-
2016-
2016/02/01 14:28:01 Trying with selected node 1
2016/02/01 14:28:01 Trying with http://172.16.33.89:8091/pools/default/bucketsStreaming/syncGW_CRUD_Lab
2016/02/01 14:28:01 Got new configuration for bucket syncGW_CRUD_Lab
2016/02/01 14:28:01 Trying with selected node 0
2016-
2016-
2016-
2016-
2016/02/01 14:28:01 Trying with http://172.16.33.88:8091/pools/default/bucketsStreaming/CRUD_Lab
2016-
2016-
2016/02/01 14:28:01 Got new configuration for bucket CRUD_Lab
As shown by the screenshot below, the CRUD_Lab data is being mirrored at syncGW_CRUD_Lab in addition to its Sync Gateway meta data while the shadow bucket CRUD_Lab is intact.
Here's a sample content of a Sync Gateway document (emp_7369):
[couchbas@lxnode4 ~]$ cbc cat emp_7369 -
emp_7369 CAS=0x2b5e55eb2e14, Flags=0x0. Size=485
{
"_sync": {
"rev": "1-
"sequence": 3,
"recent_sequences": [
3
],
"history": {
"revs": [
"1-
],
"parents": [
-
],
"bodies": [
""
],
"channels": [
null
]
},
"upstream_cas": 1453411375803007000,
"upstream_rev": "1-
"time_saved": "2016-
},
"comm": 0,
"dept": {
"deptno": 20,
"dname": "RESEARCH",
"loc": "DALLAS"
},
"empno": 7369,
"ename": "SMITH",
"hiredate": "1980/12/17",
"job": "CLERK",
"mgr": 7902,
"sal": 800
}
Both the Sync Gateway bucket and the shadow bucket synchronizes changes behind the scenes to maintain accuracy of data.