Administration Basics

Administration Basics

For quick-and-dirty configuration you can launch the sync_gateway tool with command-line flags. In the long run it's better to use a JSON configuration file, though. And configuration files are the only way to serve multiple databases.

Command-line flags

sync_gateway understands the following command-line flags. (It uses the regular Go flag parser, so flags may be prefixed with one or two - characters, and flag values can be given either as a following argument, or in the same argument after an =.)

• -adminInterface (default :4985): The port/interface the admin REST API should listen on
• -bucket (default sync_gateway): The name of the Couchbase bucket to use
• -dbname (defaults to bucket name): The name of the database to serve on the regular REST API
• -help: If given, the tool will list the allowed flags and then exit.
• -interface (default :4984): The port/interface the REST API should listen on
• -log (no default): A comma-separate list of logging keywords to enable. The HTTP keyword is always enabled, which means HTTP requests and error responses will be logged.
• -personaOrigin (no default): The server's base URL for purposes of Persona authentication. This should be the same as the URL the client reaches the server at.
• pool (default default): The Couchbase Server pool name to find buckets in
• pretty (default: false): If this flag is given, HTTP response bodies in JSON format will be pretty-printed. This is useful for debugging, but reduces performance.
• -url (default http://localhost:8091) The URL of the database server. An HTTP URL implies Couchbase Server, a walrus: URL implies the built-in Walrus database.

Examples

$ sync_gateway

--By default, connects to bucket sync_gateway of pool default of a Couchbase Server at localhost:8091. The database will be called sync_gateway and served from port 4984, with admin interface on port 4985.

$ sync_gateway -url=walrus: -bucket=db -pretty

--Creates an ephemeral in-memory Walrus database, served as db. JSON responses will be pretty-printed.

$ sync_gateway -url=walrus:///tmp/walrus -bucket=db -pretty

--Uses a Walrus database that will be persisted to file /tmp/walrus/db.walrus.

Configuration files

Instead of entering the settings on the command-line, you can store them in a JSON file and then just provide the path to that file as a command-line argument. As a bonus, the file lets you run multiple databases.

If you want to run multiple databases you can either add more entries to the databases property in the config file, or you can define each database in its own config file and list each of the config files on the command line.

Config files actually have one syntactic feature that's not standard JSON: Any text between back-quotes is treated as a string, even if it spans multiple lines. This makes it easy to embed JavaScript code, such as the sync function (which we'll get to later.)

Example

Here's a configuration file that starts a server with the default settings:

    {
        "interface": ":4984",
        "adminInterface": ":4985",
        "log": ["REST"],
        "databases": {
            "sync_gateway": {
                "server": "http://localhost:8091",
                "bucket": "sync_gateway",
                "sync": `function(doc) {channel(doc.channels);}`
            }
        }
    }

If this file is named config.json, then you'd launch the gateway as:

$ sync_gateway config.json

You can combine command-line flags with config files. This command line adds more logging:

$ sync_gateway -log=HTTP+,CRUD config.json

You can see a more complex configuration file in the CouchChat-iOS example app.

REST APIs

The gateway is accessed through two REST APIs: the public API and the admin API. These are accessed on different TCP ports -- this makes it easy to expose the public API to clients while keeping the admin API secure behind your firewall.

• The public API is used for client replication. It uses a subset of the CouchDB REST API.
• The admin API is used mostly to administrate user accounts and roles. It can also be used to look at the contents of databases in "superuser" mode.

The public API defaults to port 4984, and the admin API to port 4985. These can be changed using the interface and adminInterface properties of the config file. The value of such a property should be a string consisting of a colon : followed by a port number. A hostname or numeric IP address can be prepended before the colon to bind only to the network interface with that address.

Enabling Access

The Sync Gateway does not default to allowing anonymous/guest access. A new server isn't accessible through the public API until you either enable guest access or create some user accounts. You can do this either by editing the config file before starting the server, or by using the admin REST API.

To help you get started quickly, here's how to (temporarily) disable access control, creating an "admin party", where all data is accessible without authentication:

In a config file, users can be added in a users property inside a database object. Here's an example config file that gives full access to unauthenticated requests:

{
	"log": ["CRUD", "REST+"],
	"databases": {
		"db": {
			"users": {
				"GUEST": {"disabled": false, "admin_channels": ["*"] }
			}
		}
	}
}

The reserved username GUEST is used for all anonymous / unauthenticated access.

Alternatively, you can modify the guest account through the admin REST API:

curl -X PUT localhost:4985/$DB/_user/GUEST --data \
    '{"disabled":false, "admin_channels":["*"]}'

For more information about user accounts, see the Authentication chapter.

NEXT: Channels And Access Control