# bootstrap

Kazana supports bootstrapping of data and user accounts by using a template
folder or a custom function with callback for [custom bootstrapping](#custom-bootstrapping).

If set to a path string, [couchdb-bootstrap](https://github.com/ehealthafrica/couchdb-bootstrap)
is used to parse the folder into CouchDB databases, documents and configuration,
and write them to the CouchDB.

## Core databases

For example, if you want to to bootstrap an example raw data reports for demo
purpose, you can create `bootstrap/raw-data/bookkeeping_2016-01.json` and set
the [bootstrap option](kazana-manifest.md#bootstrap) to `"bootstrap"`.
Every time you restart the server, the raw data report will be reset, all
transformed indicator docs will be removed from `integrated-data` and re-created.

Note that names of the core databases `raw-data`, `integrated-data` and `entities`
can be configured. If you customised the names of the databases for your app,
you must use the custom database names as folder names for bootstrapping.

## Users

User accounts can be bootstrapped by creating `_users/*.json` or `_users/*.js`
documents. If the [bootstrap option](kazana-manifest.md#bootstrap) is set to
`"bootstrap"`, you could bootstrap a user with username `"joe"` and password
`"secret"` with `bootstrap/_users/org.couchdb.user_joe.json`:

```json
{
    "_id": "org.couchdb.user:joe",
    "type": "user",
    "name": "joe",
    "roles": [
        "kazana-id:uuid123",
        "kazana-data-provider"
    ],
    "password": "secret",
    "createdAt": "2015-04-15T00:00:00.000Z"
}
```

This will create / update the `org.couchdb.user:joe.json` in CouchDB’s `_users`
database. Note that the filename replaced `:` with `_` to avoid file system
issues. Most operating systems do not allow `:` in file or folder names.

If you want to set the password dynamically, you could create
`bootstrap/_users/org.couchdb.user_joe.js` instead of the `.json` file:

```js
module.exports = {
  _id: 'org.couchdb.user:joe',
  type: 'user',
  name: 'joe',
  roles: [
    'kazana-id:uuid123',
    'kazana-data-provider'
  ],
  password: process.env.TEST_USER_PASSWORD || 'secret',
  createdAt: '2015-04-15T00:00:00.000Z'
}
```

That way you can overwrite the default password (`'secret'`) by setting
the `TEST_USER_PASSWORD` environment variable.

Note that [couchdb-bootstrap](https://github.com/ehealthafrica/couchdb-bootstrap)
is smart about bootstrapping docs for `_users`. The `password` gets only changed
if it’s not the same as the current one. Setting the password in clear text to
the same as it was before would make CouchDB generate a new `salt` which in result
invalidates all user sessions.

## Custom bootstrapping

If the bootstrapping from a folder using
[couchdb-bootstrap](https://github.com/ehealthafrica/couchdb-bootstrap) is not
enough, a bootstrap function can be set.

If the [bootstrap option](kazana-manifest.md#bootstrap) is set to a function,
the [server](server.md) instance gets passed and a `callback` that needs to be
called once the bootstrap is completed. Alternatively, a promise can be returned.

In the example below, a list of entities gets read from a single JSON file and
all entities are created if they don’t yet exist, but not updated.

```js
{
  bootstrap: function (server) {
    return server.getStore({
      name: 'entities',
      auth: 'admin'
    }).findOrAdd(require('./entities.json'))
  }
}
```