Configuration Overview


    How to configure Sync Gateway for secure cloud-to-edge data sync


    Sync Gateway 3.0 introduces Centralized Persistent Modular Configuration, to better suit its use in increasingly prevalent multi-node, multi-cluster deployments. Centralized persistent modular configuration replaces the established, file-based configuration method [1], supporting the move away from a reliance on increasingly monolithic central configuration files. It enables simpler, more agile configuration updates and encompasses:

    • Bootstrap Startup
      A minimal configuration file is used to bootstrap a sync gateway node and attach it to its Couchbase Server cluster; these files and their settings are node-specific — see the Bootstrap Configuration

    • Dynamic Configuration
      The ability to make remote in-flight configuration changes to database settings, access-control policies and inter-sync gateway replications, enables simpler and more agile maintenance.

    • Cluster-aware Updates
      Configuration changes made to a node through the API endpoints are propagated to other sync gateway nodes belonging to the same cluster (or to a user-defined subset of nodes) — Configuration Groups

    • Persistent Updates
      Any database changes made using the API endpoints are persisted and survive sync gateway node restarts (this does not apply when running in file-based configuration mode).

    • Secure REST API
      by default the REST API requires authentication and authorization using Couchbase Server RBAC-user credentials — see Secure Sync Gateway Access. This can be disabled for test purposes only.

    • Automatic upgrade path
      Your existing legacy Pre-3.0 configuration files will (optionally) be automatically converted, on start-up, to the new format for centralized persistent modular configuration.


    In the Centralized Persistent Modular Configuration ecosphere you provide a minimal bootstrap configuration to get Sync Gateway started, then add users, roles, database and replications using the REST API.

    persistent config
    Figure 1. Configuration Workflow
    1. Set up a user for the Admin REST API on Couchbase Server
      Alternatively, you can disable authentication of REST API user(s) — for test purposes only

    2. Provide a bootstrap configuration file, in JSON format, which defines the sync gateway node’s run time behavior. This configuration is node-specific. Any changes require a sync gateway restart.

    3. Add or amend configuration items in-flight using the Admin Rest API.
      All changes are persisted across sync gateway restarts. Auto restarts will be initiated for ny change that requires one. You will need to configure and maintain:

      1. Databases
        Use the Admin REST API endpoint Database Configuration endpoints to add required databases.

      2. Database Security
        Use the Database Security endpoints to configure users and roles.

      3. Access Control
        Use the Access Control endpoints to configure your Sync Function.

      4. Inter-Sync Gateway replications
        Use the inter-sync gateway replication endpoints to configure required replications.


    To continue using legacy Pre-3.0 configuration you should start sync gateway with disable-persistent-config set true either in the configuration file or in Command Line Options.

    This ensures you can use the Legacy Pre-3.0 Configuration. Note that no Admin REST API changes are persisted across sync gateway restarts.

    Key Terms

    Term Description

    Sync Gateway Cluster

    A collection of sync gateway nodes connected to a common Couchbase Server cluster

    Homogeneous Sync Gateway Cluster

    A sync gateway cluster where every node in cluster shares common configuration

    Sync Gateway Config Group

    A group of sync gateway nodes within a sync gateway cluster sharing common configuration. Each node in the group will continue to have node-specific config.

    Configuration Levels

    All the configuration properties, whether defined in the bootstrap configuration file or by the Admin REST API endpoint belong to one of two core 'levels': node or database — see Table 1

    Table 1. Configuration levels in centralized persistent modular configuration
    Level Use Scope Changeable?


    Couchbase Server connection

    Minimal set of configuration properties required for connection to Couchbase Server bucket, for example server credentials, and group id

    Node-specific; unshared

    Yes, file-edit
    Restart required

    System properties

    Node level system properties including, for example, api.tls.cert_path and max_file_descriptors

    Node-specific; unshared

    Yes, file-edit
    Restart required

    Logging properties

    Logging-related properties

    Node-specific; unshared

    Yes by the Admin REST API
    No restart, but not persisted


    DB properties

    Database configuration properties including, for example, bucket, or access control policies such as users and sync

    May be node-specific, but typically shared across nodes in same group

    Yes, by Admin REST API
    Restart initiated as needed

    Replication properties

    inter-sync gateway replication properties

    Shared across all participating replication nodes

    Yes, by Admin REST API
    Restart initiated as needed

    Secure Administration

    Secure Administration is on by default.

    In order to submit Admin or Metrics REST API requests you should create specific Couchbase Server users for that purpose. You will then provide a valid set of Couchbase Server credentials for these RBAC-users in each API request.

    Authenticated users will have access to Admin and-or Metrics API functionality, application data and configuration settings.

    For more see: REST API Access

    Configuration Groups

    You can group sync gateway nodes into homogenous clusters using the Config-Group-ID property (bootstrap.group_id). This defines the database configuration group to which a node belongs.

    All nodes in a group share the same database configuration. Changes made from one node are propagated to other nodes in the group automatically.

    All nodes in a cluster belong, by default, to a common shared group default.

    If you move a sync gateway node to a new group, it will inherit the configuration associated with that group. This applies also if you move a group (back) into the default group.

    1. You can continue using file-based configuration by using the CLI option -disable_persistent_config when starting Sync Gateway