Add config-related docs;

add cookbook.md for common issue troubleshooting

README.md

@@ -9,7 +9,6 @@ Live production version:
 https://openbounty.status.im
 The `master` branch is automatically deployed here.
 
-
 Live testnet (Ropsten) version:
 https://openbounty.status.im:444
 The `develop` branch is automatically deployed here.
@@ -20,7 +19,6 @@ The `develop` branch is automatically deployed here.
 You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above installed.
 
 ### PostgreSQL
-<<<<<<< HEAD
 
 Make sure you install [PostgreSQL](https://www.postgresql.org/) and properly set it up:
 
@@ -39,7 +37,6 @@ lein figwheel
 lein less auto
 ```
 
-=======
 
 Make sure you install [PostgreSQL](https://www.postgresql.org/) and properly set it up:
 
@@ -56,9 +53,40 @@ Solidity compiler [0.4.15](https://github.com/ethereum/solidity/releases/tag/v0.
 
 Web3j [2.3.0](https://github.com/web3j/web3j/releases/tag/v2.3.0) is required and the command line tools need to be in $PATH.
 
-## Running
+## Application config
 
-Make sure `env/dev/resources/config.edn` is correctly populated.
+Make sure that `env/dev/resources/config.edn` is correctly populated. Description of config fields is given below:
+
+Key | Description
+--- | ---
+dev | Currently specifies whether Swagger UI endpoints should be added to routes
+port | HTTP port for the Ring web app
+nrepl-port | nREPL port for development
+jdbc-database-url | PostgreSQL database URL. For instance, URL to local db would be `jdbc:postgresql://localhost/commiteth?user=commiteth&password=commiteth`
+server-address | URL and port of local server that can be resolved from public internet. It will be used as a redirect URI during GitHub OAuth authorization process
+eth-account | Ethereum account ID for the bot
+eth-password | Ethereum account password for the bot
+eth-rpc-url | RPC URL to Ethereum node, e.g. Geth. Either local or remote
+eth-wallet-file | Location of wallet file. If Geth is run with the parameters as given below, it will reside under `$HOME/.ropsten/keystore`
+tokenreg-base-format | Should be set to `:status`
+github-client-id | Related to OAuth. Copied from GitHub account Settings->Developer settings->OAuth Apps
+github-client-secret | Related to OAuth. Copied from GitHub account Settings->Developer settings->OAuth Apps
+github-user | GitHub username for bot account. It is used for posting bounty comments
+github-password | GitHub password for bot account
+webhook-secret | Secret string to be used when creating a GitHub App
+user-whitelist | Set of GitHub user/org IDs to be whitelisted. E.g. `#{"status-im" "your_org"}`
+testnet-token-data | Token data map, useful if there are Geth connectivity problems
+
+## GitHub integration
+Open Bounty uses both OAuth App and GitHub App integration.
+
+### OAuth App
+Follow the steps [here](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). Specify the value of `:server-address` as "Homepage URL", and `:server-address` + `/callback` as "Authorization callback URL". Be sure to copy Client ID and Client Secret values to `config.edn`.
+
+### GitHub App
+Follow the steps [here](https://developer.github.com/apps/building-github-apps/creating-a-github-app/). Be sure to specify `:server-address` + `/webhook-app` as "Webhook URL", and `:webhook-secret` as "Webhook Secret".
+
+## Running
 
 Lauch a local geth node with the bot account unlocked:
 
@@ -141,6 +169,10 @@ Landing page is static and different CSS and JS due to time constraints.
 
 This copies over necessary artifacts to `resources` dir.
 
+
+### Troubleshooting
+See the [Cookbook](doc/cookbook.md).
+
 ## License
 
 Licensed under the [Affero General Public License v3.0](https://github.com/status-im/commiteth/blob/master/LICENSE.md)

doc/cookbook.md

@@ -0,0 +1,18 @@
+# Cookbook
+
+Here some common tasks/issues are listed along with their solutions.
+
+## Change config and restart the service
+  - ssh to the host running commiteth
+  - go to `/opt/commiteth` for prod or `/opt/commiteth-test` for test environment.
+  - there edit `config.edn`
+  - restart the service with `sudo service commiteth-test restart`
+
+## Manually add a GitHub repo to SOB app
+Sometimes SOB will not
+  - connect to Postgres instance. Get DB name and username/password from respective `config.edn` (see previous answer). These are set in `:jdbc-database-url` field.
+  - execute the query, e.g.
+```
+insert into repositories(repo_id,user_id,owner,repo,hook_id,state,hook_secret,owner_avatar_url) values(116971984,447328, 'aragon', 'aragon-monthly', 0, 2, '', 'https://avatars1.githubusercontent.com/u/24612534?v=4');
+```
+Note that the value for repo_id field is GitHub's internal repo ID. One way of obtaining it is navigating to `api.github.com/repos/:owner/:repo_name`, e.g. `https://api.github.com/repos/aragon/aragon-monthly`.

doc/testing.md

@@ -29,13 +29,9 @@ You should now see `Bounties`, `Activity`, `Repositories` and `Manage Payouts` t
 
 ### Creating bounty issues
 
-Before you can create bounties, you need to have administrative access to one or more GitHub repositories. These can be either in the scope of your personal user account or in the scope of a Github orgnazation.
+Before you can create bounties, you need to add Open Bounty GitHub App to your account or repos. Go to https://github.com/apps/status-open-bounty-app-test (or link to another GitHub App you've created for testing, as described in the [README](README.md) and click Install. Specify whether access to all org repos or specific repos is granted. This will install webhooks for SOB in your repos.
 
-* click the `Repositories` tab
+* Request for your account to be whitelisted. Contact [Riot](https://chat.status.im) for more information
-* click on the button `Enable Github Account`
-* If you have 1 or more Organisation repositories then grant Organisation access to each of them by clicking on the button `Grant` 
-* grant Status Open Bounty the needed addtional permissions for managing repository webhooks, adding and modifying comments by clicking on the button `Authorize status-open-bounty`
-* now you should see your repositories on the `Repositories` tab, click `Add` on one. If your account isn't whitelisted you will see instructions how to request an access. If your account is whitelisted then new `bounty` label will become available in the GitHub repository's labels and a new webhook should now exist for the repository.
 * now, add the `bounty` label to a new or an existing issue. This should cause Status Open Bounty to post a new comment for the issue containing an image with text `Deploying contract, please wait`
 * once the contract has been mined, the comment will be updated to contain the bounty contract's address and a QR code