Install Sync Gateway

    +

    Description — Install a Sync Gateway Instance and securely sync enterprise data from cloud to edge
    Abstract — This content explains how to install a Sync Gateway instance
    Related Content — Prepare | Verify

    Preparatory Steps
    Before starting the install, please ensure you have read, and acted-upon, the information in Prepare.

    Introduction

    Steps in Getting Started

    Introduction | Prepare | Install | Verify

    In this Getting Started topic we cover how to install the Sync Gateway package on various common platforms and how to check the installation’s success.

    You can install Sync Gateway on any of the supported operating systems.

    On completion of this topic you should have a working Sync Gateway that you can extend and configure to meet your business needs.

    Installation Process

    The installation process first deploys the Sync Gateway package, then defines and starts an example instance of Sync Gateway running as a service.

    By default Sync Gateway bases its initial setup on an example configuration file serviceconfig.json, provided in the examples directory. This initial configuration has limited functionality. It is intended primarily to verify the success of the installation by proving a connection to Sync Gateway can be made.

    Using Your Own Configuration

    Sync Gateway’s initial setup uses configuration details from a file its install script creates (sync_gateway.json, or serviceconfig.json on Windows).

    To provide your own configuration to Sync Gateway, you can either:

    • Continue to provide your config in the default file. You will need to restart Sync Gateway after each change.

    • Run Sync Gateway from a command-line. That way you can provide a path to the required config file as a parameter.

    • Change the service to use the required configuration file path.
      Instructions on how to do this are given in the Install section for each of the platforms as they differ lightly.

    You should refer to the Configuration Overview for more on the configuration process and to the Configuration Schema for details on the configuration options. We also discuss more on the initial configuration in the next Getting Started section — see: Verify. Also, the installation package itself contains example configuration files — see the appropriate install platform section for details on their location.

    Install for Linux

    In this Section

    Install | Install Locations | Run | Configuration

    Download

    Download the required edition of Sync Gateway from the Couchbase downloads page or alternatively use wget to copy the install package — see: Example 1

    Example 1. Using wget
    wget http://packages.couchbase.com/releases/couchbase-sync-gateway/2.8.2/<package-name>.<package-suffix> (1) (2)
    1 Where <package-name> is one of:
    • Enterprise Edition — couchbase-sync-gateway-enterprise_2.8.2_x86_64

    • Community Edition — couchbase-sync-gateway-community_2.8.2_x86_64

    2 Where <package-suffix> is one of:
    • Ubuntu — deb

    • Debian — deb

    • Red Hat / CentOS — rpm

    Install

    Follow the appropriate install option from the methods shown.

    • Ubuntu

    • Red Hat/CentOS

    • Debian

    Install sync_gateway with the dpkg package manager:

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

    Install sync_gateway with the rpm package manager:

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

    Install sync_gateway with the dpkg package manager:

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

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

    To stop and start the sync_gateway service, use the methods show in Run.

    Install Locations

    The default Sync Gateway installation uses the locations shown in Table 1.

    Table 1. Default Installation Locations

    Content

    Location

    Example

    Binaries

    The installation directory

    /opt/couchbase-sync-gateway/bin/

    Configuration files

    The sync_gateway user’s home directory

    /home/sync_gateway/sync_gateway.json

    Example Configs

    The installation directory

    /opt/couchbase-sync-gateway/examples/

    Log files

    The sync_gateway user’s home directory

    /home/sync_gateway/logs/

    Scripts

    The installation directory

    /opt/couchbase-sync-gateway/service/

    Service

    systemd library

    /lib/systemd/system/sync_gateway.service or /usr/lib/systemd/system/sync_gateway.service

    Run

    In a production environment you will normally run Sync Gateway as a service. However, it can also be run directly from a command line, for convenience of testing.

    • Run as a Service

    • Command Line

    Using systemd
    systemctl start sync_gateway
    systemctl stop sync_gateway
    Using init
    service sync_gateway start
    service sync_gateway stop
    Start
    (1)
    /opt/couchbase-sync-gateway/bin/sync_gateway <path-to-configuration-file> (2)
    1 Where /opt/couchbase-sync-gateway/ is the location into which you deployed the Sync Gateway package.
    2 Where <path-to-configuration-file> resolves to a JSON format file containing the Sync Gateway configuration, for example, /home/sync_gateway/sync-gateway-config.json
    Stop

    You can stop Sync Gateway instances started in this way by using Ctrl+C. There is no specific shutdown procedure and it is safe to stop it at any time. For other command-line options — see Command Line Options

    Configuration

    To change the default configuration file path of an existing Sync Gateway service you need to edit the service descriptor.

    For systemd this will be sync_gateway.service in either /lib/systemd/system/sync_gateway.service or /usr/lib/systemd/system/sync_gateway.service

    You will need to find and replace the path in following line with your required path: Environment="CONFIG=/home/sync_gateway/sync_gateway.json"

    One way to do this is to use systemctl
    1. Ensure the new file path includes a useable Sync Gateway configuration file

    2. Stop the service

    3. Copy the existing sync_gateway.service file to a safe location as a back-up

    4. Use sudo systemctl --full edit sync_gateway to edit the service
      This will create a temporary file in /etc/systemd/system/sync_gateway.d containing your changes. This file is picked-up and applied when the daemon reloads. Note, systemctl edit automatically reloads the edited unit.

    5. Replace the path in Environment="CONFIG=/home/sync_gateway/sync_gateway.json" with your required path

    6. Save the changes
      When the daemon reload completes, Sync Gateway will restart using the required configuration file

    Install for Windows

    In this Section

    Install | Install Locations | Run | Configuration

    Download

    Download the required edition of Sync Gateway from the Couchbase downloads page.

    Install

    Open the installer and follow the instructions. If the installation was successful you will see the following:

    windows installation complete

    When the installation is complete Sync Gateway will be running as a service SyncGateway.

    To stop/start the SyncGateway service, use the methods show in Run.

    Install Locations

    The default Sync Gateway installation uses the locations shown in Table 2.

    Table 2. Default Installation Locations

    Content

    Location

    Binaries

    C:\Program Files\Couchbase\Sync Gateway\

    Configuration files

    C:\Program Files\Couchbase\Sync Gateway\

    Examples

    C:\Program Files\Couchbase\Sync Gateway\examples

    Log files

    C:\Program Files\Couchbase\Sync Gateway\var\lib\couchbase\logs

    Tools

    C:\Program Files\Couchbase\Sync Gateway\tools

    Run

    In a production environment you will normally run Sync Gateway as a service. However, it can also be run directly from a command line, for convenience of testing.

    • Run as a Service

    • Command Line

    Using the Windows' Services Application
    1. From the Start Menu, Control Panel → Admin Tools → Services

    2. Within the Service panel, locate and Right-Click the service

    3. From the Options Menu, select Start (or Stop) Enter

    Using Windows' Command Line Utility sc.exe
    1. Start Sync Gateway Service

      c:\> sc start SyncGateway

      This will result in a response such as:

      SERVICE_NAME: SyncGateway
              TYPE               : 10  WIN32_OWN_PROCESS
              STATE              : 2  START_PENDING
                                      (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)
              WIN32_EXIT_CODE    : 0  (0x0)
              SERVICE_EXIT_CODE  : 0  (0x0)
              CHECKPOINT         : 0x0
              WAIT_HINT          : 0x7d0
              PID                : 7420
              FLAGS              :
    2. Stop Sync Gateway Service

      c:\> sc stop SyncGateway

      This will result in a response such as:

      SERVICE_NAME: SyncGateway
              TYPE               : 10  WIN32_OWN_PROCESS
              STATE              : 4  RUNNING
                                      (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN)
              WIN32_EXIT_CODE    : 0  (0x0)
              SERVICE_EXIT_CODE  : 0  (0x0)
              CHECKPOINT         : 0x0
              WAIT_HINT          : 0x0
    Start
    c:\PROGRA~1\COUCHB~1\SYNCGA~1\SYNC_G~1.EXE <path-to-configuration-file> (1)
    1 Where:
    • The path to the executable uses Windows' short name notation

    • <path-to-configuration-file> resolves to a JSON format file containing the Sync Gateway configuration, for example, {home-location-windows}sync-gateway-config.json

    Stop

    You can stop Sync Gateway instances started in this way by using Ctrl+C. There is no specific shutdown procedure and it is safe to stop it at any time. For other command-line options — see Command Line Options

    Configuration

    To change the default configuration file path of an existing Sync Gateway service you need to edit the service descriptor.

    For Windows, the configuration path is provided as a command line parameter embedded within the SyncGateway service’s binpath.

    One way to edit the binpath value is to use Windows' Service Control Manager’s command line utility sc.exe config. See the Syntax of the sc.exe Command and an example of the command in use in Example 2.

    Syntax of the sc.exe Command

    The format of the sc.exe command is shown below. For presentation purposes it is split over several lines. It should be input as a single line.

    sc <remote-server-name> (1)
      config (2)
      SyncGateway (3)
      binpath= (4)
      " (5)
      [path-to-sg-windows.exe] start [path-to-sync_gateway.exe] (6)
      [path-to-config-file] (7)
      [path-to-error-logs] (8)
      " (9)
    1 Omit the <remote-server-name> parameter if the service is local
    2 Specifies the function we are using, config, in this instance
    3 Identifies the service being changed
    4 Specifies the string value of the path to the binary to be run, and any command line parameters. The rules for formatting the binpath value are quite complex:
    • The entire string value must be enclosed in quotes

    • There must be one space (only) following the equals sign and none before it

    • Each of the [path-to …​] elements must themselves be enclosed in quotes. These inner quotes must be escaped (for example \" …​ \")

    5 Opening quotes for the binpath, preceded by a single space.
    6 Path to the binaries.
    7 You can provide the required configuration file path name here in the form:
    \"path/to/file/name.json\"
    8 You can provide the required log file path name here in the form:
    \"path/to/file/name.log\"
    9 Closing quotes for the binpath, preceded by a single space.
    Example 2. Sample sc.exe Use

    This example changes the configuration file name from serviceconfig.json to sync-gateway-config.json

    sc config SyncGateway binpath= "\"C:\Program Files\Couchbase\Sync Gateway\sg-windows.exe\" start \"C:\Program Files\Couchbase\Sync Gateway\sync_gateway.exe\" \"C:\Program Files\Couchbase\Sync Gateway\sync-gateway-config.json\" \"C:\Program Files\Couchbase\Sync Gateway\var\lib\couchbase\logs\sync_gateway_error.log\""

    Install for Mac OS

    In this Section

    Install | Install Locations | Run | Configuration

    Download

    Download the required edition of Sync Gateway from the Couchbase downloads page or alternatively use wget to copy the install package — see: Example 3

    Example 3. Using wget
    1 Where <package-name> is one of:
    • Enterprise Edition — couchbase-sync-gateway-enterprise_2.8.2_x86_64

    • Community Edition — couchbase-sync-gateway-community_2.8.2_x86_64

    Install

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

      sudo tar -zxvf couchbase-sync-gateway-enterprise_2.8.2_x86_64.tar.gz --directory /opt
    2. 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
    3. 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
    4. Define the Sync Gateway Service

      This script will define and load the service, which is set it to automatically restart.

      Other scripts in the service directory are available to update or uninstall the service.

      cd /opt/couchbase-sync-gateway//service
      sudo ./sync_gateway_service_install.sh <optional-args> (1)
      1 Note that you can, by using optional parameters, provide alternative file paths for the Sync Gateway configuration file (--cfgpath=) or log files () path (--logsdir=). These will be used instead of the default path whenever the service starts.

      So, for example:
      sudo ./sync_gateway_service_install.sh --cfgpath=sync-gateway-config.json

    5. When the install is complete the sync_gateway service will be running

      To stop/start the sync_gateway service, use the methods show in Run

    Install Locations

    The default Sync Gateway installation uses the locations shown in Table 3.

    Table 3. Default Installation Locations

    Content

    Location

    Example

    Binaries

    The installation directory

    /opt/couchbase-sync-gateway/bin/

    Configuration files

    The sync_gateway user’s home directory

    /users/sync_gateway/

    Examples

    The installation directory

    /opt/couchbase-sync-gateway/examples/

    Log files

    The sync_gateway user’s home directory

    /users/sync_gateway/logs/

    Scripts

    The installation directory

    /opt/couchbase-sync-gateway/service/

    Service

    Library directory

    /Library/LaunchDaemons/com.couchbase.mobile.sync_gateway.plist

    Run

    In a production environment you will normally run Sync Gateway as a service. However, it can also be run directly from a command line, for convenience of testing.

    • Run as a Service

    • Command Line

    sudo launchctl load -w /Library/LaunchDaemons/com.couchbase.mobile.sync_gateway.plist (1)
    
    sudo launchctl unload -w /Library/LaunchDaemons/com.couchbase.mobile.sync_gateway.plist (2)
    1 Here we load, and automatically start, the default sync_gateway service
    2 Here we unload the default sync_gateway service. Note that it is not sufficient to stop the service. It is configured to automatically restart.
    Start
    (1)
    /opt/couchbase-sync-gateway/bin/sync_gateway <path-to-configuration-file> (2)
    1 Where /opt/couchbase-sync-gateway/ is the location into which you deployed the Sync Gateway package.
    2 Where <path-to-configuration-file> resolves to a JSON format file containing the Sync Gateway configuration, for example, /users/sync_gateway/sync-gateway-config.json
    Stop

    You can stop Sync Gateway instances started in this way by using Ctrl+C. There is no specific shutdown procedure and it is safe to stop it at any time. For other command-line options — see Command Line Options

    Configuration

    To change the default configuration file path of an existing Sync Gateway service you need to edit the service descriptor.

    For Mac OS this will be the .plist file com.couchbase.mobile.sync_gateway.plist.

    One way to do this would be:
    1. Ensure the new file path includes a useable Sync Gateway configuration file

    2. Within a terminal, stop the service — see: start and stop the service

    3. Copy the existing com.couchbase.mobile.sync_gateway.plist file to a safe location as a back-up

    4. Open the com.couchbase.mobile.sync_gateway.plist file in an editor. You will need to use sudo

    5. Within the ProgramArguments section of the .plist, find and edit the configuration file path, which by default contains: <string>/Users/sync_gateway/sync_gateway.json</string>

    6. Save your changes

    7. Restart the service  — see: start and stop the service

    Check the Install

    To check Sync Gateway started successfully, you can now connect to it from a browser by using either:

    You should receive a response in the browser such as:
    {"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":"2.8"},"version":"Couchbase Sync Gateway/2.8.2(145;e3f46be) EE"}

    If you do encounter issues in getting an operational install of Sync Gateway, you can find some useful information in the log files. Refer to the Logging page for how to configure different logging levels to aid troubleshooting.

    Next Steps

    Now that you have a working version of Sync Gateway, which you can connect a console to using either the Public or Admin REST API, you can:

    Getting Started
    Community