Administration Basics

Administration Basics

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.

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

{
    "interface": ":4984",
    "adminInterface": ":4985",
    "log": ["CRUD", "REST"],
    "databases": {
        "sync_gateway": {
            "server": "http://localhost:8091",
            "bucket": "sync_gateway"
        }
    }
}

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

$ sync_gateway config.json  

If you want to run multiple databases you can either add more entries to the databases property in the config file, or you can put each of them in its own config file (just like above) and list each of the config files on the command line.

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 supports a subset of the CouchDB REST API.
• The Administration Basics 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

Unlike CouchDB, 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 what CouchDB calls 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