4. Configuration

Local Configuration

The following config files are placed in each CouchApp directory.

.couchapprc and couchapp.json

Every CouchApp MUST have a .couchapprc file in the application directory; the couchapp.json is optional.

Both files are a JSON object which contains configuration parameters that the command-line app uses to build and push your CouchApp. Note that if they contain the same fields, the .couchapprc will win.

The couchapp generate and couchapp init commands create a default version of this file for you.

So, what’s diff between .couchapprc and couchapp.json? Usually, we will put not only configs but some metadata into couchapp.json. couchapp.json will be published via couchapp push; the .couchapprc won’t.

The valid fields in .couchapprc:

env:Place your db credentials here. This field is .couchapprc only. extensions:List of your custom extensions. hooks:Your custom hooks. vendors:List of your vendor handlers.

{
    "env": {
        // ...
    },
    "extensions": [
        // ...
    ],
    "hooks": {
        // ...
    },
    "vendors": [
        // ...
    ]
}

The valid fields in couchapp.json:

Changed in version 1.1

The env is not available here. Also, do not place any private credentials in this file. This file will be distributed via couchapp push.

{
    // other metadata here
    // "name": "myCouchApp",
    // "version": 1.0,
    // ...
    "extensions": [
        // ...
    ],
    "hooks": {
        // ...
    },
    "vendors": [
        // ...
    ]
    // ...
}

Example

The most common use for the .couchapprc file is to specify one or more CouchDB databases to use as the destination for the couchapp push command. Destination databases are listed under the env key of the .couchapprc file as follows:

{
  "env" : {
    "default" : {
      "db" : "http://localhost:5984/mydb"
    },
    "prod" : {
      "db" : "http://admin:password@myhost.com/mydb"
    }
  }
}

In this example, two environments are specified: default, which pushes to a local CouchDB instance without any authentication, and prod, which pushes to a remote CouchDB that requires authentication. Once these sections are defined in .couchapprc, you can push to your local CouchDB by running:

couchapp push

(the environment name default is used when no environment is specified) and push to the remote machine using:

couchapp push prod

For a more complete discussion of the env section of the .couchapprc file, see the Managing Design Documents chapter of CouchDB: The Definitive Guide.

.couchappignore

A .couchappignore file specifies intentionally untracked files that couchapp should ignore. It’s a simple json file containing an array of regexps that will be use to ignore file.

For example:

[
  ".*\\.swp$",
  ".*~$"
]

will ignore all files ending in .swp and ~. Be sure to leave out the final , in the list.

You can check if couchapp really ignores the files by specifying the -v option:

couchapp -v push

Note

Windows doesn’t like files that only have an extension, so creating the .couchappignore file will be a challenge in windows. Possible solutions to creating this file are:

Using cygwin, type:

cd /path/to/couchapp
touch .couchappignore

and then notepad .couchappignore.

Global Configuration

~/.couchapp.conf

One drawback to declaring environments in the .couchapprc file is that any usernames and passwords required to push documents are stored in that file. If you are using source control for your CouchApp, then those authentication credentials are checked in to your (possibly public) source control server. To avoid this problem, the couchapp tool can also read environment configurations from a file stored in your home directory named .couchapp.conf. This file has the same syntax as .couchapprc but has the advantage of being outside of the source tree, so sensitive login information can be protected.

If you already have a working .couchapprc file, simply move it to ~/.couchapp.conf and run couchapp init to generate a new, empty .couchapprc file inside your CouchApp directory. If you don’t have a .couchapprc file, couchapp will display the dreaded couchapp error: You aren't in a couchapp message.

~/.couchapp/

Please see App Template.

Todo

more information about other templates like vendor, view, etc.