From d154cad3f6d33414a0f8d6002a103f47919620ff Mon Sep 17 00:00:00 2001
From: Chance Zibolski <chance@coreos.com>
Date: Mon, 21 Sep 2015 15:45:53 -0700
Subject: [PATCH] Documentation: Add how to setup email configuration

---
 Documentation/email-configuration.md | 52 ++++++++++++++++++++++++++++
 Documentation/getting-started.md     | 11 ++++--
 2 files changed, 60 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/email-configuration.md

diff --git a/Documentation/email-configuration.md b/Documentation/email-configuration.md
new file mode 100644
index 00000000..2a5d4b04
--- /dev/null
+++ b/Documentation/email-configuration.md
@@ -0,0 +1,52 @@
+# Configuring Sending Emails
+
+Dex sends emails to a during the registration process to verify an email
+address belongs to the person signing up. Currently Dex supports two ways of
+sending emails, and has a third option for use during development.
+
+Configuration of the email provider in Dex is provided through a JSON file. All
+email providers have a `type` and `id` field as well as some additional provider
+specific fields.
+
+## SMTP
+
+If using SMTP the `type` field **must** be set to `smtp`. Additionally both
+`host` and `port` are required. If you wish to use SMTP plain auth, then
+set `auth` to `plain` and specify your username and password.
+
+```
+{
+    "type": "smtp",
+    "host": "smtp.example.org",
+    "port": 587,
+    "auth": "plain",
+    "username": "postmaster@example.org",
+    "password": "foo"
+}
+```
+
+## Mailgun
+
+If using Mailgun the `type` field **must** be set to `mailgun`. Additionally
+`privateAPIKey`, `publicAPIKey`, and `domain` are required.
+
+```
+{
+    "type": "mailgun",
+    "privateAPIKey": "key-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+    "publicAPIKey": "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
+    "domain": "sandboxZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ.mailgun.org"
+}
+```
+
+## Dev
+
+The fake emailer should only be used in development. The fake emailer
+prints emails to `stdout` rather than sending any email. If using the fake
+emailer the `type` field **must** be set to `fake`.
+
+```
+{
+    "type": "fake"
+}
+```
\ No newline at end of file
diff --git a/Documentation/getting-started.md b/Documentation/getting-started.md
index 073086f9..9ae3aa32 100644
--- a/Documentation/getting-started.md
+++ b/Documentation/getting-started.md
@@ -46,7 +46,7 @@ The dex overlord and workers allow multiple key secrets (separated by commas) to
 
 # 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. 
+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-secrets=$DEX_KEY_SECRET --log-debug=true &`
 
@@ -63,7 +63,12 @@ export DEX_OVERLORD_LOG_DEBUG=true
 
 # Start the dex-worker
 
-Now start the worker:
+Before starting `dex-worker` you should determine how you want verification emails to be delivered to the user.
+If you just want to test dex out, you can just use the provided sample config in `static/fixtures/emailer.json.sample`.
+Please review [email-configuration](https://github.com/coreos/dex/blob/master/Documentation/email-configuration.md) for details
+(make sure you point `--email-cfg` to your newly configured file).
+
+Once you have setup your email config run `dex-worker`:
 
 `./bin/dex-worker --db-url=$DEX_DB_URL --key-secrets=$DEX_KEY_SECRET --email-cfg=static/fixtures/emailer.json.sample --log-debug=true &`
 
@@ -75,7 +80,7 @@ Note: the issuer URL MUST have an `https` scheme in production to meet spec comp
 
 The worker and overlord are up and running, but we need to tell dex what connectors we want to use to authenticate. For this case we'll set up a local connector, where dex manages credentials and provides a UI for authentication, and a Google OIDC connector.
 
-If you prefer to use the Google OIDC Identity Provider (IdP), just omit the second entry in the JSON connector list. Note that you must replace DEX_GOOGLE_CLIENT_{ID,SECRET} with the client ID and client Secret you got when you registered your project with the Google developer console. 
+If you prefer to use the Google OIDC Identity Provider (IdP), just omit the second entry in the JSON connector list. Note that you must replace DEX_GOOGLE_CLIENT_{ID,SECRET} with the client ID and client Secret you got when you registered your project with the Google developer console.
 ```
 cat << EOF > /tmp/dex_connectors.json
 [