Add database documentation

docs/GETTING_STARTED.md

@@ -102,9 +102,23 @@ and respond to requests.
 
 * `dnsNames`: comma separated list of DNS Name(s) for the CA.
 
-* `logger`: the default logging format for the CA is `text`. The other options
+* `logger`: the default logging format for the CA is `text`. The other option
 is `json`.
 
+* `db`: data persistence layer. See [database documentation](./db.md) for more
+info.
+
+    - type: `badger`, `bbolt`, `mysql`, etc.
+
+    - dataSource: `string` that can be interpreted differently depending on the
+    type of the database. Usually a path to where the data is stored. See
+    the [database configuration docs](./db.md#configuration) for more info.
+
+    - database: name of the database. Used for backends that may have
+    multiple databases. e.g. MySQL
+
+    - valueDir: directory to store the value log in (Badger specific).
+
 * `tls`: settings for negotiating communication with the CA; includes acceptable
 ciphersuites, min/max TLS version, etc.
 

docs/database.md

@@ -0,0 +1,95 @@
+# Step Certificates Database
+
+`step certificates` uses a simple key-value interface over popular database
+implementations to store persistent certificate management meta-data.
+
+Our recommended default database implementation is
+[nosql-Badger](https://github.com/smallstep/nosql/badger) - a NoSQL interface
+over the popular [Badger](https://github.com/dgraph-io/badger) database.
+
+## What will the database store?
+
+As a first pass, the database layer will store every certificate (along with
+metadata surrounding the provisioning of the certificate) and revocation data
+that will be used to enforce passive revocation.
+
+## Implementations
+
+Current implementations include Badger (default), BoltDB, and MysQL.
+
+- [ ] Memory
+- [x] [BoltDB](https://github.com/etcd-io/bbolt) -- etcd fork.
+- [x] [Badger](https://github.com/dgraph-io/badger)
+- [x] [MariaDB/MySQL](https://github.com/go-sql-driver/mysql)
+- [ ] PostgreSQL
+- [ ] Cassandra
+- [ ] ...
+
+Let us know which integration you would like to see next by opening an issue or PR.
+
+## Configuration
+
+Configuring `step certificates` to use a database is as simple as adding a
+top-level `db` stanza to your `step-ca.config` (see getting started doc for
+more info).  Below are a few examples for supported databases:
+
+### Badger
+
+```
+{
+  ...
+  "crt": ".step/certs/intermediate_ca.crt",
+  "key": ".step/secrets/intermediate_ca_key",
+  "db": {
+    "type": "badger",
+    "dataSource": "./stepdb",
+    "valueDir": "./steplogdb"   # leave empty if equivalent to dataSource
+  },
+  ...
+},
+```
+
+### BoltDB
+
+```
+{
+  ...
+  "crt": ".step/certs/intermediate_ca.crt",
+  "key": ".step/secrets/intermediate_ca_key",
+  "db": {
+    "type": "bbolt",
+    "dataSource": "./stepdb"
+  },
+  ...
+},
+```
+
+### MySQL
+
+```
+{
+  ...
+  "crt": ".step/certs/intermediate_ca.crt",
+  "key": ".step/secrets/intermediate_ca_key",
+  "db": {
+    "type": "mysql",
+    "dataSource": "user:password@tcp(127.0.0.1:3306)/",
+    "database": "myDatabaseName"
+  },
+  ...
+},
+```
+
+## Schema
+
+As the interface is a key-value store, the schema is very simple. We support
+`tables`, `keys`, and `values`. An entry in the database is a `[]byte value`
+that is indexed by `[]byte table` and `[]byte key`.
+
+## Data Backup
+
+Backing up your data is important, and it's good hygiene. We chose
+[Badger](https://github.com/dgraph-io/badger) as our default file based data
+storage backend because it has mature tooling for running common database
+tasks. See the [documentation](https://github.com/dgraph-io/badger#database-backup)
+for a guide on backing up your data.