Documentation: bring dev-guide up to date.

Documentation/dev-guide.md

@@ -1,11 +1,20 @@
 # Dev Guide
 
+## No DB mode
+
+When you are working on dex it's convenient to use the "--no-db" flag, which starts up Dex in a mode which uses an in-memory datastore for persistence. It also does not rotate keys, so no overlord is required.
+
+In this mode you provide the binary with paths to files to connectors and users - there are example files you can use inside of `static/fixtures`, named "connectors.json.sample" and "users.json.sample" respectively. If you rename these to the equivalent without the ".sample", the defaults point to this location, making starting dex as simple as:
+
+`./bin/dex-worker  --no-db`
+
+*Do not use this flag in production* - it's not thread safe and data is destroyed when the process dies. In addition, there is no key rotation.
 
 ## Building
 
 To build using the go binary on your host, use the `./build` script.
 
-You can also use a copy of `go` hosted inside a docker container if you prefix your command with `go-docker`, as in: `./go-docker ./build`
+You can also use a copy of `go` hosted inside a Docker container if you prefix your command with `go-docker`, as in: `./go-docker ./build`
 
 ## Docker Build and Push
 
@@ -17,6 +26,8 @@ export DOCKER_PASSWORD=<<your password>>
 ./build-docker-push
 ```
 
+By default the script pushes to `quay.io/coreos/dex`; if you want to push to a different repository, override the `DOCKER_REGISTRY` and `DOCKER_REPO` environment variables.
+
 ## Rebuild API from JSON schema
 
 Go API bindings are generated from a JSON Discovery file.
@@ -28,18 +39,30 @@ To regenerate run:
 
 For updating generator dependencies see docs in: `schema/generator_import.go`.
 
-## Runing Tests
+## Running Tests
 
-Run all tests: `./test`
+To run all tests (except functional) use the `./test` script; 
 
-Single package only: `PKG=<pkgname> ./test`
+If you want to test a single package only, use `PKG=<pkgname> ./test`
 
-Functional tests: `./test-functional`
+The functional tests require a database; create a database (eg. `createdb dex_func_test`) and then pass it as an environment variable to the functional test script, eg.  `DEX_TEST_DSN=postgres://localhost/dex_func_test?sslmode=disable ./test-functional`
+
+To run these tests with Docker is a little trickier; you need to have a container running Postgres, and then you need to link that container to the container running your tests:
 
-Run with docker:
 
 ```
-./go-docker ./test
-./go-docker ./test-functional
+# Run the Postgres docker container, which creates a db called "postgres"
+docker run --name dex_postgres -d postgres
+
+# The host name in the DSN is "postgres"; that works because that is what we
+# will alias the link as, which causes Docker to modify /etc/hosts with a "postgres"
+# entry.
+export DEX_TEST_DSN=postgres://postgres@postgres/postgres?sslmode=disable
+
+# Run the test container, linking it to the Postgres container.
+DOCKER_LINKS=dex_postgres:postgres DOCKER_ENV=DEX_TEST_DSN ./go-docker ./test-functional docker
+
+# Remove the container after the tests are run.
+rm -f dex_postgres
 ```
 

Documentation/getting-started.md

@@ -14,7 +14,7 @@ We'll also start the example web app, so we can try registering and logging in.
 Before continuing, you must have the following installed on your system:
 
 * Go 1.4 or greater
-* Postgres 9.0 or greater
+* Postgres 9.0 or greater (this guide also assumes that Postgres is up and running)
 
 In addition, if you wish to try out authenticating against Google's OIDC backend, you must have a new client registered with Google:
 
@@ -42,11 +42,13 @@ dex needs a 32 byte base64-encoded key which will be used to encrypt the private
 
 `DEX_KEY_SECRET=$(dd if=/dev/random bs=1 count=32 2>/dev/null | base64)`
 
+The dex overlord and workers allow multiple key secrets (separated by commas) to be passed but only the first will be used to encrypt data; the rest are there for decryption only; this scheme allows for the rotation of keys without downtime (assuming a rolling restart of workers).
+
 # Start the overlord
 
 The overlord is responsible for creating and rotating keys and some other adminsitrative tasks. In addition, the overlord is responsible for creating the necessary database tables (and when you update, performing schema migrations), so it must be started before we do anything else. Debug logging is turned on so we can see more of what's going on. Start it up. 
 
-`./bin/dex-overlord --db-url=$DEX_DB_URL --key-secret=$DEX_KEY_SECRET --log-debug=true &`
+`./bin/dex-overlord --db-url=$DEX_DB_URL --key-secrets=$DEX_KEY_SECRET --log-debug=true &`
 
 ## Environment Variables.
 

README.md

@@ -31,7 +31,7 @@ A typical dex deployment consists of N dex-workers behind a load balanacer, and
 The dex-workers directly handle user requests, so the loss of all workers can result in service downtime.
 The single dex-overlord runs its tasks periodically, so it does not need to maintain 100% uptime.
 
-## Who Should Use AuthD?
+## Who Should Use Dex?
 
     **TODO**