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

Verify a Sync Gateway Install

      +

      Configure and verify your Sync Gateway installation; securely sync enterprise data from cloud to edge!
      This is Step 4 in the Start Here! topic group. Here we will verify that you can connect your Sync Gateway to a Couchbase Server and synchronize changes whether made in Couchbase Server or through Sync Gateway’s REST API.

      Related Start Here! topics: Introduction | Prepare | Install

      Preparatory Steps
      Before following the steps in this topic you must have read, and acted-upon, the information and steps in Prepare and Install.

      Introduction

      Steps in Getting Started

      Introduction | Prepare | Install | Verify

      In this final step of the Getting Started topic we will look to link your Sync Gateway to a Couchbase Server bucket and verify that sync is taking place by executing a CRUD cycle. You will need to edit the configuration file used in the Install step to point to a bucket on your Couchbase Server — see Configure Sync Gateway.

      On completion of this topic you will have a working Sync Gateway instance that you know syncs with a Couchbase Server. You will have successfully completed installation and can now build on this with confidence.

      Configure Sync Gateway

      To configure Sync Gateway to connect to a Couchbase Server:

      1. Ensure your Sync Gateway service is stopped/unloaded

      2. Edit the configuration file you used in Install and replace the contents with those shown in Example 1.

        The configuration points to the get-started-bucket which we will use to verify that you can synchronize changes made through the Sync Gateway API with those made through Couchbase Server.

      3. Ensure you start Couchbase Server

      4. Restart/Load your Sync Gateway to pick-up the changed configuration

      Example 1. Simple Sync Gateway-Couchbase Server Config
      {
  "adminInterface": "127.0.0.1:4985",
  "interface": "0.0.0.0:4984",
  "databases": {
    "get-started-bucket": {
      "server": "http://127.0.0.1:8091",
      "bucket": "get-started-bucket", (1)
      "username": "sync_gateway", (2)
      "password": "password",
      "enable_shared_bucket_access": true, (3)
      "import_docs": true, (4)
      "num_index_replicas": 0, (5)
      "users": {
        "GUEST": { "disabled": false, "admin_channels": ["*"] } (6)
      }
    }
  },
  "logging": { (7)
    "console": {
      "log_level": "debug",
      "log_keys": ["*"]
    }
  }
}
      About the Configuration Properties
      1 Here we point to the Couchbase Server bucket you created in Configure Server for Sync Gateway
      2 Provided the credentials for the RBAC user that you created on the Couchbase Server Admin Console — see Configure Server for Sync Gateway
      3 Set enable_shared_bucket_access true to allow both Sync Gateway and Couchbase Server to make changes to the same bucket. This works in conjunction with import_docs to facilitate the replication of changes whether made through Sync Gateway or externally by an App or Couchbase Server SDK for example.
      4 Set import_docs true to allow import processing to take place on this Sync Gateway node, thereby integrating document changes made outside of Sync Gateway
      5 num_index_replicas is the number of index replicas stored in Couchbase Server — see Indexing versus Views.
      NOTE: If you’re running a single Couchbase Server node for development purposes the num_index_replicas must be set to 0.
      6 Here users introduces a guest user with access to all channels and all documents
      7 Define your logging requirements:
      Here we set general diagnostic console logs on. If you’re having issues then refer to Logging for how to tune diagnostics to provide additional troubleshooting help

      Connect to Sync Gateway

      You can use Console Logs to aid diagnosis of connection issues

      1. With Sync Gateway and Couchbase Server started, point your browser to the Sync Gateway url, typically on port 4984, but this can be changed — see: REST API Access.

        So, for example:

        http://localhost:4984

      2. Check that you receive a response similar to this:

        {"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":"2.8"},"version":"Couchbase Sync Gateway/{version-full}(376;e2e7d42) EE"}

        If there are issues then check the Console Logs for more information. Where necessary you can redirect console output to a file — see: Redirect Console Logs.

      If Sync Gateway is behind a load balancer then check the websockets configuration — see Load Balancer.

      Verify the CRUD Cycle

      Here we will use CURL and Sync Gateway’s REST API to

      1. Create a New Document: Use the API to add a document and check the document on Couchbase Server

      2. Get a Document Using the API: Read the document back from Couchbase Server using the Sync Gateway API

      3. Update a Document using API: Update the newly created document and observe the changes in Couchbase Server

      4. Sync a Couchbase Server Change Update the document in Couchase Server and check the change in Sync Gateway

      5. Delete a Document Using API Delete our document and check its state on Couchbase Server and Sync Gateway.

      Create a New Document:

      Within a terminal use CURL to issue the following POST request, which adds a new document to the Couchbase Server bucket get-started-bucket by way of the Sync Gateway database get-started-bucket we configured in Configure Sync Gateway

      Request
      curl --location -g --request POST 'http://localhost:4984/get-started-bucket/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "_id": "first-doc",
  "name": "Verify-Install Topic",
  "type": "get-started",
  "data": "any random string"
}'
      Response
      {"id":"first-doc","ok":true,"rev":"1-a46e9c2f8ff4581e5662c47ae8519b0e"}%
      Check

      View the document in Couchbase Server Admin Console to verify it syncs from Sync Gateway database.

      1. Within the Admin Console, select Buckets and hit the Documents button to open the Document Editor tab.

      2. Within the Document Editor tab:

        1. Enter get-started-bucket as Bucket

        2. Enter first as Document ID

        3. Enter

          You will see the response shown in Figure 1. The document should include any changes made through Sync Gateway, including the initial create.

          cbs view first doc
          Figure 1. Couchbase Server Document Editor

      Get a Document Using the API:

      Request
      curl --location --request GET 'http://localhost:4984/get-started-bucket/first-doc'
      Response
      {"_id":"first-doc","_rev":"1-a46e9c2f8ff4581e5662c47ae8519b0e","data":"any random string","name":"Verify-Install Topic","type":"get-started"}%

      Update a Document using API:

      Request
      curl --location -g --request PUT 'http://localhost:4984/get-started-bucket/first-doc' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "_id": "first-doc",
  "_rev": "1-a46e9c2f8ff4581e5662c47ae8519b0e", (1)
  "name": "Verify-Install Topic",
  "type": "get-started",
  "data": "an edited string" (2)
}'
      1 This revision is the one returned by the response to the initial POST request — see: Response to Add Document Request
      2 Here we change the text of the data field.
      Response
      {"id":"first-doc","ok":true,"rev":"2-ecbdda61df3290beff4d0e433af8d745"}%  (1)
      1 Here the "ok":true indicates success, whilst the revision shows it is the second change to this document.
      Check

      Check Document on Couchbase Server. Does the document contain the changed data value?

      Sync a Couchbase Server Change

      This will show that changes made using Couchbase Server are replicated to Sync Gateway.

      1. Within the Couchbase Server Document Editor

        1. Retrieve first_doc if it is not currently displayed

        2. Edit the data value to contain "an edited string also changed in server"

        3. Save the change.

      2. In your terminal, use the API to get the document again — see Get a Document Using the API:
        You should see the change you made in Couchbase Server reflected in the response. For example:

        {"_id":"first-doc","_rev":"3-cc2e758ef63b0daf5b01b2baf98c72b6", (1)
"data":"an edited string also changed in server", (2)
"name":"Verify-Install Topic","type":"get-started"}
        1 Note that the revision sequence is now 3, up from the 2 returned in our Response to Update Document Request
        2 Note that the data field now contains both the change made in Sync Gateway ("an edited string") and that made in Couchbase Server ("also changed in server")

      Delete a Document Using API

      Request
      curl --location -g --request DELETE 'http://localhost:4984/get-started-bucket/first-doc?rev=3-cc2e758ef63b0daf5b01b2baf98c72b6' (1)
      1 Note that we provide here the revision ID of the latest revision (3), as returned in the response to the last GET request.
      Response

      You should see the following response:

      {"id":"first-doc","ok":true,"rev":"4-03f1ba127340e8c50c31a36279298e60"}%  (1)
      1 You can see here that the delete counts as the fourth change/revision. Again "ok":true indicates the delete was successful.
      Check

      Ways to Verify Sync

      To verify that document changes have been replicated, you can:

      • Monitor the Sync Gateway revision number returned by the database endpoint (GET /{tkn-db}/). The revision number increments for every change that happens on the Sync Gateway database.

      • Query a document by ID on the Sync Gateway REST API as shown in Check Document on Couchbase Server. Use (GET /{tkn-db}/{id}) — see: REST API Access for more.

      • Query a document from the Query Workbench on the Couchbase Server Console.

      Next Steps

      Now you know Sync Gateway is deployed and operational. So, you can explore more complex scenarios with confidence.

      Maybe you want to learn more about Sync Gateway’s Configuration Schema or how to Sync with Couchbase Server. Or perhaps you want to explore how to:

      Related Content

      Getting Started
      Product Information
      Community