Getting Started

Install Couchbase Server

Before installing Sync Gateway, you must install and configure Couchbase Server.

Download and install Couchbase Server.

Creating a bucket

Open the Couchbase Server Admin Console on http://localhost:8091 and log on using your administrator credentials.
In the toolbar, select the Buckets tab and click the Add Bucket button.
In the pop-up window, enter getting-started-bucket for the name and click Add Bucket. You can leave the other options to their defaults.

Creating an RBAC user

In order for Sync Gateway to connect to Couchbase Server, you must create an RBAC user. The RBAC user credentials will be used in a later section to start Sync Gateway.

Open the Security tab and click the Add User button.
The steps to create the RBAC user differ slightly depending on the version of Couchbase Server that you have installed. We explain the differences below.
- Couchbase Server 5.5 or above
- Couchbase Server 5.1
In the pop-up window, provide a Username (sync_gateway) and Password (password). Those credentials will be used by Sync Gateway to connect to Couchbase Server (in the Configure Sync Gateway section). You must grant RBAC roles to that user. If you are using Couchbase Server 5.5 or above, you must enable the Application Access and Read Only Admin roles as shown on the image below.

In the pop-up window, provide a Username and Password, those credentials will be used by Sync Gateway to connect later on. Next, you must grant RBAC roles to that user. If you are using Couchbase Server 5.1, you must enable the Bucket Full Access and Read Only Admin roles.

Network access

If you’re installing Couchbase Server on the cloud, make sure that network permissions (or firewall settings) allow incoming connections to Couchbase Server ports. In a typical mobile deployment on premise or in the cloud (AWS, Red Hat, etc.), the following ports must be opened on the host for Couchbase Server to operate correctly: 8091, 8092, 8093, 8094, 11207, 11210, 11211, 18091, 18092, 18093. You must verify that any firewall configuration allows communication on the specified ports. If this is not done, the Couchbase Server node can experience difficulty joining a cluster. You can refer to the Couchbase Server Network Configuration guide to see the full list of available ports and their associated services.

Install Sync Gateway

Install Sync Gateway on the operating system of your choice:

Enterprise Edition

Ubuntu
Red Hat/CentOS
Debian
Windows
macOS

Download Sync Gateway from the Couchbase downloads page or using wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-enterprise_2.7.0_x86_64.deb

Install sync_gateway with the dpkg package manager e.g:

dpkg -i couchbase-sync-gateway-enterprise_2.7.0_x86_64.deb

When the installation is complete sync_gateway will be running as a service.

To stop/start the sync_gateway service, use the following.

sudo service sync_gateway start
sudo service sync_gateway stop

The config file and logs are located in /home/sync_gateway.

You can also run the sync_gateway binary directly from the command line. The binary is installed at /opt/couchbase-sync-gateway/bin/sync_gateway.

Download Sync Gateway from the Couchbase downloads page or using the wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-enterprise_2.7.0_x86_64.rpm

Install sync_gateway with the rpm package manager e.g:

rpm -i couchbase-sync-gateway-enterprise_2.7.0_x86_64.rpm

When the installation is complete sync_gateway will be running as a service.

On CentOS 5:

service sync_gateway start
service sync_gateway stop

On CentOS 6:

initctl start sync_gateway
initctl stop sync_gateway

The initctl restart sync_gateway command does not work in CentOS 6. To restart Sync Gateway, the stop/start commands can be used instead.

On CentOS 7:

systemctl start sync_gateway
systemctl stop sync_gateway

The config file and logs are located in /home/sync_gateway.

Download Sync Gateway from the Couchbase downloads page or using the wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-enterprise_2.7.0_x86_64.deb

Install sync_gateway with the dpkg package manager e.g:

dpkg -i couchbase-sync-gateway-enterprise_2.7.0_x86_64.deb

When the installation is complete sync_gateway will be running as a service.

systemctl start sync_gateway
systemctl stop sync_gateway

The config file and logs are located in /home/sync_gateway.

Download Sync Gateway from the Couchbase downloads page. Open the installer and follow the instructions. If the installation was successful you will see the following.

Sync Gateway runs as a service (reachable on http://localhost:4985). To stop/start the service, you can use the Services application (Control Panel → Admin Tools → Services).

The configuration file is located under C:\Program Files\Couchbase\Sync Gateway\serviceconfig.json.
Logs are located under C:\Program Files\Couchbase\Sync Gateway\var\lib\couchbase\logs.

macOS is supported only for development and test environments (see Supported OS).

Download Sync Gateway from the Couchbase downloads page or using the wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-enterprise_2.7.0_x86_64.tar.gz

From here, there are two installation options.

Option 1: Start Sync Gateway from the Command Line

Unpack the tar.gz installer.

sudo tar -zxvf couchbase-sync-gateway-enterprise_2.7.0_x86_64.tar.gz

Launch the sync_gateway program from the command line.
```
~/Downloads/couchbase-sync-gateway/bin/sync_gateway
```

Option 2: Run Sync Gateway as a service

Unpack the tar.gz installer to the /opt directory.

sudo tar -zxvf couchbase-sync-gateway-enterprise_2.7.0_x86_64.tar.gz --directory /opt

Create a new macOS user.

sudo sysadminctl -addUser sync_gateway

If the operation is successful, you will get the following output.

sysadminctl ----------------------------
sysadminctl No clear text password or interactive option was specified (adduser, change/reset password will not allow user to use FDE) !
sysadminctl ----------------------------
sysadminctl Creating user record…
sysadminctl Assigning UID: 505
sysadminctl Creating home directory at /Users/sync_gateway

Create a new group and add the sync_gateway user to that group.

sudo dseditgroup -o create sync_gateway
sudo dseditgroup -o edit -a sync_gateway -t user sync_gateway

Run Sync Gateway as a service with the following.
```
cd /opt/couchbase-sync-gateway/service
sudo ./sync_gateway_service_install.sh
```
Other scripts in that directory are available to update or uninstall the service.
Sync Gateway is now reachable on 0.0.0.0:4984. The configuration file and logs are located in /Users/sync_gateway.

The following sections describe how to install and configure Sync Gateway to run with Couchbase Server.

Community Edition

Ubuntu
Red Hat/CentOS
Debian
Windows
macOS

Download Sync Gateway from the Couchbase downloads page or using wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-community_2.7.0_x86_64.deb

Install sync_gateway with the dpkg package manager e.g:

dpkg -i couchbase-sync-gateway-community_2.7.0_x86_64.deb

When the installation is complete sync_gateway will be running as a service.

To stop/start the sync_gateway service, use the following.

sudo service sync_gateway start
sudo service sync_gateway stop

The config file and logs are located in /home/sync_gateway.

You can also run the sync_gateway binary directly from the command line. The binary is installed at /opt/couchbase-sync-gateway/bin/sync_gateway.

Download Sync Gateway from the Couchbase downloads page or using the wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-community_2.7.0_x86_64.rpm

Install sync_gateway with the rpm package manager e.g:

rpm -i couchbase-sync-gateway-community_2.7.0_x86_64.rpm

When the installation is complete sync_gateway will be running as a service.

On CentOS 5:

service sync_gateway start
service sync_gateway stop

On CentOS 6:

initctl start sync_gateway
initctl stop sync_gateway

The initctl restart sync_gateway command does not work in CentOS 6. To restart Sync Gateway, the stop/start commands can be used instead.

On CentOS 7:

systemctl start sync_gateway
systemctl stop sync_gateway

The config file and logs are located in /home/sync_gateway.

Download Sync Gateway from the Couchbase downloads page or using the wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-community_2.7.0_x86_64.deb

Install sync_gateway with the dpkg package manager e.g:

dpkg -i couchbase-sync-gateway-community_2.7.0_x86_64.deb

When the installation is complete sync_gateway will be running as a service.

systemctl start sync_gateway
systemctl stop sync_gateway

The config file and logs are located in /home/sync_gateway.

Download Sync Gateway from the Couchbase downloads page. Open the installer and follow the instructions. If the installation was successful you will see the following.

Sync Gateway runs as a service (reachable on http://localhost:4985). To stop/start the service, you can use the Services application (Control Panel → Admin Tools → Services).

The configuration file is located under C:\Program Files\Couchbase\Sync Gateway\serviceconfig.json.
Logs are located under C:\Program Files\Couchbase\Sync Gateway\var\lib\couchbase\logs.

Download Sync Gateway from the Couchbase downloads page or using the wget.

wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.7.0/couchbase-sync-gateway-community_2.7.0_x86_64.tar.gz

From here, there are two installation options.

Option 1: Start Sync Gateway from the Command Line

Unpack the tar.gz installer.

sudo tar -zxvf couchbase-sync-gateway-community_2.7.0_x86_64.tar.gz

Launch the sync_gateway program from the command line.
```
~/Downloads/couchbase-sync-gateway/bin/sync_gateway
```

Option 2: Run Sync Gateway as a service

Unpack the tar.gz installer to the /opt directory.

sudo tar -zxvf couchbase-sync-gateway-community_2.7.0_x86_64.tar.gz --directory /opt

Create a new macOS user.

sudo sysadminctl -addUser sync_gateway

If the operation is successful, you will get the following output.

sysadminctl ----------------------------
sysadminctl No clear text password or interactive option was specified (adduser, change/reset password will not allow user to use FDE) !
sysadminctl ----------------------------
sysadminctl Creating user record…
sysadminctl Assigning UID: 505
sysadminctl Creating home directory at /Users/sync_gateway

Create a new group and add the sync_gateway user to that group.

sudo dseditgroup -o create sync_gateway
sudo dseditgroup -o edit -a sync_gateway -t user sync_gateway

Run Sync Gateway as a service with the following.
```
cd /opt/couchbase-sync-gateway/service
sudo ./sync_gateway_service_install.sh
```
Other scripts in that directory are available to update or uninstall the service.
Sync Gateway is now reachable on 0.0.0.0:4984. The configuration file and logs are located in /Users/sync_gateway.

Configure Sync Gateway

The following steps explain how to connect Sync Gateway to the Couchbase Server instance.

Open a new file called sync-gateway-config.json with the following.

Default
With Import Filter

{
  "log": ["*"],
  "databases": {
    "getting-started-db": {
      "server": "http://localhost:8091",
      "bucket": "getting-started-bucket",
      "username": "sync_gateway", (1)
      "password": "password", (2)
      "enable_shared_bucket_access": true, (3)
      "import_docs": true,
      "num_index_replicas": 0, (4)
      "users": {
        "GUEST": { "disabled": false, "admin_channels": ["*"] }
      },
      "sync": `function (doc, oldDoc) {
        if (doc.sdk) {
          channel(doc.sdk);
        }
      }`
    }
  }
}

Configuration properties:

1	The user’s username that you created on the Couchbase Server Admin Console.
2	The user’s password that you created on the Couchbase Server Admin Console.
3	The shared bucket access feature allows Couchbase Server SDKs to also perform operations on this bucket.
4	`num_index_replicas` is the number of index replicas stored in Couchbase Server, introduced with GSI/N1QL indexing. If you’re running a single Couchbase Server node for development purposes the `num_index_replicas` must be set to `0`.

For clusters with a large amount of data, the initial import process can take considerable time to complete. Therefore, to get started with a cluster which contains a large number of pre-existing documents, we recommend to use an import_filter to reduce the initial import processing time.

{
  "log": ["*"],
  "databases": {
    "getting-started-db": {
      "server": "http://localhost:8091",
      "bucket": "getting-started-bucket",
      "username": "sync_gateway", (1)
      "password": "password", (2)
      "enable_shared_bucket_access": true, (3)
      "import_docs": true,
      "num_index_replicas": 0, (4)
      "import_filter": `
        function(doc) { (5)
          if (doc.type != "mobile") {
            return false
          }
          return true
        }`,
      "users": {
        "GUEST": { "disabled": false, "admin_channels": ["*"] }
      },
      "sync": `function (doc, oldDoc) {
        if (doc.sdk) {
          channel(doc.sdk);
        }
      }`,
    }
  }
}

Configuration properties:

1	The user’s username that you created on the Couchbase Server Admin Console.
2	The user’s password that you created on the Couchbase Server Admin Console.
3	The shared bucket access feature allows Couchbase Server SDKs to also perform operations on this bucket.
4	`num_index_replicas` is the number of index replicas stored in Couchbase Server, introduced with GSI/N1QL indexing. If you’re running a single Couchbase Server node for development purposes the `num_index_replicas` must be set to `0`.
5	Only import documents which have a `type` property equal to `mobile`.

Start Sync Gateway from the command line, or if Sync Gateway is running in a service replace the configuration file and restart the service.
```
~/Downloads/couchbase-sync-gateway/bin/sync_gateway ~/path/to/sync-gateway-config.json
```
Run the application where Couchbase Lite is installed.
To verify that documents have been replicated, you can:
- Monitor the Sync Gateway sequence number returned by the database endpoint (GET /{db}/). The sequence number increments for every change that happens on the Sync Gateway database.
- Query a document by ID on the Sync Gateway REST API (GET /{db}/{id}).
- Query a document from the Query Workbench on the Couchbase Server Console.

Network Ports

Sync Gateway uses specific ports for communication with the outside world, mostly Couchbase Lite databases replicating to and from Sync Gateway. The following table lists the ports used for different types of Sync Gateway network communication:

Port	Description
4984	Public port. External HTTP port used for replication with Couchbase Lite databases and other applications accessing the REST API on the Internet. The Public REST API is used for client replication. The default port for the Public REST API is 4984.
4985	Admin port. Internal HTTP port for unrestricted access to the database and to run administrative tasks. The Admin REST API is used to administer user accounts and roles. It can also be used to look at the contents of databases in superuser mode. The default port for the Admin REST API is 4985. By default, the Admin REST API is reachable only from localhost for safety reasons.

Port

Description

4984

Public port. External HTTP port used for replication with Couchbase Lite databases and other applications accessing the REST API on the Internet.

The Public REST API is used for client replication. The default port for the Public REST API is 4984.

4985

Admin port. Internal HTTP port for unrestricted access to the database and to run administrative tasks.

The Admin REST API is used to administer user accounts and roles. It can also be used to look at the contents of databases in superuser mode. The default port for the Admin REST API is 4985. By default, the Admin REST API is reachable only from localhost for safety reasons.

The APIs are accessed on different TCP ports, which makes it easy to expose the Public REST API on port 4984 to endpoints while keeping the Admin REST API on port 4985 secure behind your firewall.

If you want to change the ports, you can do that in the configuration file.

To change the Public REST API port, set the interface property in the configuration file.
To change the Admin REST API port, set the adminInterface property in the configuration file.

The value of the property is a string consisting of a colon followed by a port number (for example, :4985). You can also prepend a host name or numeric IP address before the colon to bind only to the network interface with that address.

As a useful special case, the IP address 127.0.0.1 binds to the loopback interface, making the port unreachable from any other host. This is the default setting for the admin interface.