Prepare to Install Sync Gateway

What You Need

Here’s what you need to install Sync Gateway:

To know whether your set-up meets the Minimum Requirements and Compatibility Requirements for running Sync Gateway
To have access to a working Couchbase Server deployment configured for Sync Gateway or know how to Deploy Couchbase Server
To Configure Server for Sync Gateway, including creating an appropriate set of RBAC users, ready for use in Sync Gateway and in the REST API
Have appropriate network credentials and Network Access

Once you have all that covered … go Install Sync Gateway.

Couchbase Server Requirements

To use Sync Gateway you need an operational Couchbase Server installation. Verify that you use compatible versions of Couchbase Server and Sync Gateway — see: Compatibility Requirements.

You can get Couchbase Server from the Downloads page

You’ll then need to configure Couchbase Server by adding a Bucket and an RBAC User for Sync Gateway — see: Configure Server for Sync Gateway.

Users of Couchbase Server 6.0 should ensure they have addressed the known issue (MB-41255) by upgrading to one of the recommended Couchbase Server versions (6.0.5, 6.5.2, or 6.6.1).

The known issue can cause re-balance failures and/or failed replica writes of deleted or expired documents that use Xattrs.

This impacts Sync Gateway deployments running with shared bucket access enabled, which use Xattrs for metadata storage.

Network Port Requirements

Sync Gateway uses specific ports for communication with the outside world, mostly Couchbase Lite databases replicating to and from Sync Gateway — see Table 1 for details.

Table 1. Sync Gateway Network Port Requirements
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.
4986	Metrics port. By default `4986` is the internal HTTP port designated for providing access to Sync Gateway’s Metrics REST API. Like the admin port, it is bound to `127.0.0.1` by default. The Metrics REST API returns Sync Gateway metrics, in JSON and-or Prometheus-compatible formats, for performance monitoring and-or diagnostic purposes,

Couchbase Server Host Ports

For mobile deployment on premise or in the cloud (for example, AWS or Red Hat) open the following ports on the host to enable Couchbase Server to operate correctly:

Unencrypted: 8091-8093, 11210
Encrypted: 18091-18093, 11207

Check that any firewall configuration allows communication on the specified ports.

Compatibility with Couchbase Server

Users of Couchbase Server 6.0 should ensure they have addressed the known issue (MB-41255) by upgrading to one of the recommended Couchbase Server versions (6.0.5, 6.5.2, or 6.6.1).

The known issue can cause re-balance failures and/or failed replica writes of deleted or expired documents that use Xattrs.

This impacts Sync Gateway deployments running with shared bucket access enabled, which use Xattrs for metadata storage.

Table 2. Sync Gateway/Couchbase Server Compatibility Matrix
Sync Gateway ↓		Couchbase Server →
Version	Scenario	8.0.0	7.6.5	7.6.4	7.6	7.2	7.1
4.0.0
4.0.0	Bidirectional Active-Active XDCR
3.3.0
3.2.0
3.1.0
3.0.3
2.5-2.8	`shared_bucket_access: false` `use_views: true`
2.5-2.8	`shared_bucket_access: true`
2.5-2.8	`use_views: false`
2.1	`shared_bucket_access: false` `use_views: true`
2.1	`shared_bucket_access: true`
2.1	`use_views: false`
2.0	`shared_bucket_access: false`
2.0	`shared_bucket_access: true`

Starting from CBS 7.0, the use_views feature is deprecated.

SGW 3.1 will only run with use_views with a default scope/collection configuration
You cannot run use_views with a defined scope/collection

Sync Gateway 4.0 requires CBS 7.6.1+. Active-Active XDCR requires CBS 7.6.5+. Sync Gateway 3.x does not support Active-Active XDCR.

Couchbase Server Bucket Types

Use only Couchbase bucket types in Couchbase Mobile. We do not support the use of Couchbase Server’s Ephemeral or Memcached bucket types — for more on bucket types see: Couchbase Server bucket types.

Compatibility with Couchbase Server 5.0-7.0

For Couchbase Server versions 5.0, 5.1, 5.5-6.0, and 6.5-7.0:

Sync Gateway 4.0.0 is not compatible with these versions
Sync Gateway 3.x and 2.x versions are fully compatible with these versions

Compatibility with Couchbase Lite

The table below summarizes the compatible versions of Couchbase Lite with Sync Gateway.

Table 3. Sync Gateway and Couchbase Lite Compatibility Matrix
Sync Gateway Versions ↓	Couchbase Lite →
Sync Gateway Versions ↓	1.4 ^[1]	2.0	2.1	2.5 - 2.8	3.0.0	3.1.0	3.2.0	3.3.0	4.0.0
1.4 ^[2] and 1.5 ^[3]
2.0 and 2.1
2.5 to 2.8 with delta sync disabled
2.5 to 2.8 with delta sync enabled
3.0.0
3.1.0
3.2.0
3.3.0
4.0.0

Couchbase Lite 4.0 requires Sync Gateway 4.0.

Couchbase Lite 4.0 is only compatible with Sync Gateway 4.0. Connecting Couchbase Lite 4.0 to Sync Gateway versions before 4.0 is not supported due to version vector architecture changes. However, Sync Gateway 4.0 is compatible with all supported Couchbase Lite versions (2.0+), allowing customers to upgrade Sync Gateway first.

Supported Operating Systems

Table 4. Supported Operating Systems for Development, Testing, and Production
Operating System	Supported Versions
Red Hat Enterprise Linux (RHEL)	10.x
Red Hat Enterprise Linux (RHEL)	9.x
Alma Linux	9.x
Rocky Linux	9.x
Ubuntu	24.04 LTS ARM, 24.04 LTS x86
Ubuntu	22.04 LTS ARM, 22.04 LTS x86
Debian	13.x
	12.x
	11.x
Windows Server	2022

Table 5. Supported Operating Systems for Development and Testing Only
Operating System	Supported Versions
macOS	15 M1 ARM64, 15 x86
macOS	14 M1 ARM64, 14 x86
Windows Desktop	11
Windows Desktop	10

Table 6. Supported Cloud Environments for Development, Testing, and Production
Platform	Operating System	Supported Versions
AWS	Amazon Linux	2023 LTS (ARM, x86)
AWS	Ubuntu	24.04 LTS (ARM, x86)
Azure	Ubuntu	24.04 LTS (ARM, x86), 22.04 LTS (ARM, x86)
Google Cloud	Ubuntu	24.04 LTS (ARM, x86) 22.04 LTS (ARM, x86)
OpenShift (RedHat Portal)	RHEL	10
OpenShift (RedHat Portal)	RHEL	9
Ubuntu		24.04 LTS, 22.04 LTS

Cluster Configuration for Sync Gateway

Create a new cluster on a fresh Couchbase Server installation.

Access the Admin Console at http://localhost:8091
Select Setup New Cluster
Fill in the details for the new cluster on the New Cluster screen:
Then press Next: Accept Terms
On the Terms and Conditions screen, accept the terms and conditions, then Select Configure Disk, Memory, Services to configure the cluster.
Verify that you have selected Data, Query, and Index before selecting Save & Finish

Configure Server for Sync Gateway

Step 1 — Create a Bucket

Use this bucket to test the deployment of Sync Gateway, later in the Getting Started section.

Login to Couchbase Server’s Admin Console
1. Go to http://localhost:8091
2. Enter your administrator credentials.

Within the Admin Console’s toolbar,

Select the Buckets tab
Select Add Bucket to continue

In the pop-up window, enter get-started-bucket for the name and select Add Bucket. You can leave the other options to their defaults.

Couchbase Server Bucket Types

Use only Couchbase bucket types in Couchbase Mobile. We do not support the use of Couchbase Server’s Ephemeral or Memcached bucket types — for more on bucket types see: Couchbase Server bucket types.

Step 2 — Create RBAC User

You’ll need to create at least one RBAC user in Couchbase Server as sync gateway requires RBAC user credentials to authenticate and authorize access not only to Couchbase Server buckets, but also to its Admin and Metrics API. If you plan to use these API then create at least one user for each of:

Couchbase Server Access
Add an RBAC user that Sync Gateway uses to authenticate and authorize access to Couchbase Server. Use the sync_gateway role.
Admin API
Add an RBAC user that administrators can use to authenticate and authorize access to the sync gateway Admin REST API Use the Full Admin role.
Metrics API
Add an RBAC user that devops can use to authenticate and authorize access to the sync gateway Metrics REST API Use the Read-Only Admin or Application Access roles.

Enterprise edition users can exert a finer-grained control using additional roles appropriate to the capabilities required for the specific user.

For more on creating Couchbase Server users see: Server — Manage Users and Roles.

Step 3 — Set-up Network Access

When installing Couchbase Server on the cloud, make sure that network permissions (or firewall settings) allow incoming connections to Couchbase Server ports.

For mobile deployment on premise or in the cloud (for example, AWS or Red Hat) open the following ports on the host to enable Couchbase Server to operate correctly:

Unencrypted: 8091-8093, 11210
Encrypted: 18091-18093, 11207

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

For more information, see the Couchbase Server Ports guide to see the full list of available ports and their associated services.

Getting Started

Product Information

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

1. This Couchbase Lite version is End of Support

2. This Sync Gateway version is End of Support

3. This Sync Gateway version is End of Life

Prepare to Install Sync Gateway

What You Need

Couchbase Server Requirements

Network Port Requirements

Couchbase Server Host Ports

Compatibility with Couchbase Server

Compatibility with Couchbase Lite

Supported Operating Systems

Cluster Configuration for Sync Gateway

Configure Server for Sync Gateway

Step 1 — Create a Bucket

Step 2 — Create RBAC User

Step 3 — Set-up Network Access

Related Content