Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Prepare to Install Sync Gateway

      +

      Prerequisites for installing Sync Gateway; to synchronize your data from cloud to edge.
      This is Step 2 in the Start Here! topic group. It introduces the prerequisites for the installation of Sync Gateway

      Related Start Here! topics: Introduction | Install | Verify

      Introduction

      Steps in Getting Started

      Introduction | Prepare | Install | Verify

      In this Getting Started topic we will discuss the prerequisites you need to have in place before you begin installing the Sync Gateway package.

      On completion of this page you should:

      Your next step will be covered in Install

      Couchbase Requirements

      Before you can usefully use Sync Gateway, you will need an operational Couchbase Server installation. You should ensure that you are using compatible versions of Couchbase Server and Sync Gateway — see: Compatibility Requirements.

      You can get Couchbase Server from our Downloads page

      You will 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 →

      4.0[1]

      4.1[1]

      4.5[1]

      4.6[1]

      5.0

      5.1

      5.5-7.1

      1.3[2]

      feed_type: "DCP"

      ✖

      ✖

      ✖

      ✖

      ✔

      ✔

      ✔

      1.4[2] feed_type: "DCP"

      ✖

      ✖

      ✖

      ✖

      ✔

      ✔

      ✔

      1.5[3]

      shared_bucket_access: false

      ✔

      ✔

      ✔

      ✔

      ✔

      ✔

      ✔

      1.5[3]

      shared_bucket_access: true

      ✖

      ✖

      ✖

      ✖

      ✔

      ✔

      ✔

      2.0

      shared_bucket_access: false

      ✔

      ✔

      ✔

      ✔

      ✔

      ✔

      ✔

      2.0

      shared_bucket_access: true

      ✖

      ✖

      ✖

      ✖

      ✔

      ✔

      ✔

      2.1

      shared_bucket_access: false

      use_views: true

      ✔

      ✔

      ✔

      ✔

      ✔

      ✔

      ✔

      2.1

      shared_bucket_access: true

      ✖

      ✖

      ✖

      ✖

      ✔

      ✔

      ✔

      2.1

      use_views: false

      ✖

      ✖

      ✖

      ✖

      ✖

      ✖

      ✔

      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

      ✖

      ✖

      ✖

      ✖

      ✖

      ✖

      ✔
      Couchbase Server Bucket Types
      Use only Couchbase bucket types in Couchbase for Mobile and Edge. 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 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 →

      1.4 [4]

      2.0

      2.1

      2.5 - 2.8

      3.0.0

      3.1.0

      3.2.0

      1.4 [2] and 1.5 [3]

      yes

      no

      no

      no

      no

      no

      no

      2.0 and 2.1

      yes

      yes

      yes

      yes

      yes

      yes

      yes

      2.5 to 2.8
      with delta sync disabled

      yes

      yes

      yes

      yes

      yes

      yes

      yes

      2.5 to 2.8
      with delta sync enabled

      no

      no

      no

      yes

      yes

      yes

      yes

      3.0.0

      no

      yes

      yes

      yes

      yes

      yes

      yes

      3.1.0

      no

      yes

      yes

      yes

      yes

      yes

      yes

      3.2.0

      no

      yes

      yes

      yes

      yes

      yes

      yes

      Supported Operating Systems

      Table 4. Supported Operating Systems for Development, Testing, and Production
      Operating System Supported Versions

      Red Hat Enterprise Linux (RHEL)

      7.x and 8.x

      CentOS

      7.x and 8.x

      Ubuntu

      16.04 LTS and 18.04

      Debian

      8.x and 9.x

      Windows Server

      2012 (64-bit) DEPRECATED at Sync Gateway 2.8+ 2016 (64-bit)
      Table 5. Supported Operating Systems for Development and Testing Only
      Operating System Supported Versions

      macOS

      10.15(Catalina)
      10.14 (Mojave)

      Windows Desktop

      2010
      Table 6. Supported Cloud Environments for Development, Testing, and Production
      Platform Operating System Supported Versions

      AWS

      Amazon Linux AMI

      2017.09
      2018.03

      Azure

      Ubuntu

      16.04

      Google Cloud

      Ubuntu

      16.04

      Docker (Docker Hub)

      CentOS

      7

      OpenShift (RedHat Portal)

      RHEL

      7.2

      Configure Server for Sync Gateway

      STEP 1 — Create a Bucket

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

      1. Login to Couchbase Server’s Admin Console

        1. Go to http://localhost:8091

        2. Enter your administrator credentials

      2. Within the Admin Console’s toolbar,

        1. Select the Buckets tab

        2. Add Bucket to continue

          cb create bucket

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

          Couchbase Server Bucket Types
          Use only Couchbase bucket types in Couchbase for Mobile and Edge. 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.
        cb create bucket popup

      STEP 2 — Create RBAC User

      To connect to Couchbase Server, you must create an RBAC user. These user credentials are used in a later section to start Sync Gateway.

      1. Open the Security tab and click the Add User button.

        create user

      2. Create the RBAC user with appropriate access roles.

        The steps to do this are shown in Example 1. Note that they differ, depending on your Couchbase Server version.

        Example 1. Select RBAC roles

        • Couchbase Server 6.6+ (Enterprise)

        • Couchbase Server 5.5 - 6.x

        • Couchbase Server 5.1

        This content relates only to ENTERPRISE EDITION

        1. In the pop-up window, provide

          • A Username (sync_gateway)

          • A Password (password).

        2. Assign the Sync Gateway role to the user

          Sync Gateway RBAC Role Description

          user settings 6 6
          Users are encouraged to move away from using the Application Access and Read-Only Admin roles for this purpose.

        1. In the pop-up window, provide:

          • A Username (sync_gateway)

          • A Password (password).

        2. Assign these RBAC roles to the user(as shown on the image below):

          • Application Access

          • Read Only Admin

            user settings 5 5

        1. In the pop-up window, provide:

          • A Username (sync_gateway)

          • A Password* (password).

        2. Assign these RBAC roles to the user:

          • Bucket Full Access

          • Read Only Admin

        user settings

      STEP 3 — Set-up Network Access

      When installing Couchbase Server on the cloud, ensure 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.

      You can refer to the Couchbase Server Ports guide to see the full list of available ports and their associated services.

      Related Content

      Getting Started
      Product Information
      Community
      1. This Couchbase Server version is End of Support
      2. This Sync Gateway version is End of Support
      3. This Sync Gateway version is End of Life
      4. This Couchbase Lite version is End of Support