update README with config file setup + OAuth instructions

README.md

@@ -24,9 +24,40 @@ Run the `_build/default/src/notabot.exe` binary. The following commands are supp
 - `check_gh <GH_PAYLOAD>`: read a Github notification from a file and display the actions that will be taken (used for testing)
 - `check_slack <SLACK_PAYLOAD>`: read a Slack notification from a file and send it to a channel (used for testing)
 
-### Documentation
+## Getting Started
 
-The bot expects two configuration files to be present.
+1. Upload a **repository configuration** file to the root of your target repository.
+1. Place a **secrets** file locally on the server.
+1. Configure GitHub
+    1. If targeting a private repository, set up a [personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with `repo` scope and store it in the `gh_token` field of the secrets file.
+    1. [Create a webhook](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/creating-webhooks#setting-up-a-webhook) for the repository you are targeting. Set the *Payload URL* to be `<server_domain>/github`.
+    1. You can optionally [secure the webhook](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/securing-your-webhooks) with a token, and store it in the `gh_hook_token` field of the secrets file.
+1. Configure Slack
+    1. [Create a Slack app](https://api.slack.com/apps?new_app=1). Click on "Basic Information" in the left sidebar, and update your secrets file with the `slack_client_id` and `slack_client_secret` with information from the page. You can optionally provide the `slack_signing_secret` to enforce [signature checking](https://api.slack.com/authentication/verifying-requests-from-slack) on incoming requests from Slack.
+    1. Click on "OAuth & Permissions" in the sidebar. Give your bot a *Bot Token Scope* of `chat:write`.
+    2. Click "Install to Workspace", and when prompted to grant permissions to your workspace, click "Allow".
+    3. Copy the generated OAuth access token (`xoxb-XXXX`) to the `slack_access_token` field of your secrets file. This token is used by the bot to authenticate to the workspace, and remains valid until the token is revoked or the app is uninstalled.
+
+### OAuth Authorization
+
+If you are preparing the app for distribution, you also need to enable automatic OAuth exchange.
+
+You should...
+
+1. In your Slack app dashboard, click on "OAuth & Permissions" in the sidebar. Set the *Redirect URL* to be `<server_domain>/slack`, and ensure your bot has a *Bot Token Scope* of `chat:write`.
+1. You can optionally provide a value for `slack_oauth_state` in your secrets file to [avoid forgery attacks](https://tools.ietf.org/html/rfc6749#section-4.1.1) during the OAuth exchange.
+1. Launch the server with the `run` command. Make sure it's reachable externally from same the `server_domain` you used for the GitHub Payload URL. The bot server will listen on `/slack` for incoming OAuth requests.
+1. When the server completes an OAuth exchange and doesn't have an access token defined yet, the secrets file on the server will be regenerated to include a `slack_access_token` field.
+
+Your users should...
+
+1. Go to the following address, replacing the appropriate values (the `state` argument is only needed if you set `slack_oauth_state` in the previous step). `https://slack.com/oauth/v2/authorize?scope=chat:write&client_id=<slack_client_id>&redirect_uri=<server_domain>/slack&state=<slack_oauth_state>`
+1. A page should open asking for permission to install the bot to the workspace. When prompted, click "Allow".
+1. Add the bot to all Slack channels the user wants to send notifications to.
+
+## Documentation
+
+You should configure two files as part of initial setup. Read on for more information on their respective file structure.
 
 * [Repository configuration](./documentation/config_docs.md)
 * [Secrets](./documentation/secret_docs.md)