Skip to content

Installing And Upgrading

Jump to bottom
Traun Leyden edited this page Jun 27, 2013 · 10 revisions

Installation and First Launch

The Sync Gateway is known to work on Mac OS X, Windows and Ubuntu Linux. (And it should work on any platform supported by the Go language.) It has no external dependencies.

Using a precompiled build

The latest stable build of the gateway is available:

  • For Mac OS (Requires Mac OS X 10.6 or later and a 64-bit CPU)
  • Linux and Windows builds coming soon

In the unzipped folder next to this README.md file will be an executable file called sync_gateway. Simply run it as you would any other command-line tool. (You will probably want to move it to some directory in your shell $PATH, for convenience.)

If you are curious how these build artifacts came to be, read How we build at Couchbase

Building from source

  1. Check out the Sync Gateway Git repository wherever you want
  2. cd to the checkout directory
  3. run git submodule init; git submodule update
  4. run ./build.sh (on Mac or other Unix systems, or Windows using Cygwin. We don't have an equivalent Windows .bat file yet, though it's a trivial script and would be easy to port. If you do so, please send us a copy!)
  5. The compiled gateway is bin/sync_gateway. It's a standalone native executable; you can move it wherever you want or just run it directly from the build location.

To update your build later on, just pull the new revisions and run ./build.sh again.

Quick startup

Now that you have the gateway, start it from a shell using the following arguments:

sync_gateway -url walrus:

That's it! You now have a sort of mock-CouchDB listening on port 4984 (and with an admin API on port 4985.) It has a single database called "sync_gateway". It definitely won't do everything CouchDB does, but you can tell another CouchDB-compatible database (including TouchDB) to replicate with it.

(To use a different database name, use the -dbname flag: e.g. -dbname mydb.)

The gateway is using a simple in-memory database called Walrus instead of Couchbase Server. This is very convenient for quick testing. Walrus is so simple, in fact, that by default it doesn't persist its data to disk at all, so every time the sync_gateway process exits it loses all of its data! Great for unit testing, not great for any actual use. You can make your database persistent by changing the -url value to a path to an already-existing filesystem directory:

mkdir /data
sync_gateway -url walrus:/data

Relative paths are also supported, eg:

mkdir data
sync_gateway -url walrus:data

If you are using the config.json, it would look like this:

{
        "databases": {
                "couchchat": {
                        "server": "walrus:data"
        ...
}

The gateway will now periodically save its state to a file /data/sync_gateway.walrus. This is by no means highly scalable, but it will work for casual use.

Connecting with a real Couchbase server

Using a real Couchbase server, once you've got one set up, is as easy as changing the URL:

  1. Install and start Couchbase Server 2.0 or later.
  2. Create a bucket named sync_gateway in the default pool.
  3. Start the sync gateway with an argument -url followed by the HTTP URL of the Couchbase server:
    sync_gateway -url http://localhost:8091

If you want to use a different name for the bucket, or listen on a different port, you can do that with command-line options. Use the --help flag to see a list of options.

NEXT: Administration Basics

Clone this wiki locally