Update docs

README.md → docs/README.md

@@ -74,17 +74,22 @@ Technically, the system is architected:
 * __Web 3 Bridge__ This is the bridge between web3 and the rest of the application. Mostly built in javascript(web3js) and python(web3py).
 * __Brochureware__ Just a nice little landing page telling folks what the Gitcoin project is.
 
-# Developing 
+# Developing
 
 ## HTTPS API
 
-[For more information on the HTTPS API, please view the api README](readme_api.md)
+[For more information on the HTTPS API, please view the api README](API.md)
 
-## Running Locally
+## Running Locally with Docker (Recommended)
 
-[For more information on running the app locally, please view the running locally README](readme_runninglocally.md)
+[For more information on running the app locally, please view the running locally README](./docs/RUNNING_LOCALLY_DOCKER.md)
+
+## Running Locally without Docker
+
+[For more information on running the app locally, please view the running locally README](./docs/RUNNING_LOCALLY.md)
 
 # Trying out Gitcoin
+
 ## Posting your first issue
 
 If you
@@ -100,7 +105,7 @@ try posting a funded issue at [https://gitcoin.co/new](https://gitcoin.co/new).
 
 This widget will help you advertise that you support Gitcoin bounties, so that your community knows the best place to contribute.
 
-[Check out the widget readme to learn how](readme_widget.md)
+[Check out the widget readme to learn how](./docs/WIDGET.md)
 
 ## Adding GitcoinBot to your repo
 
@@ -117,7 +122,7 @@ Have an ERC20 compatible token that you'ud like to add support for?  Great!
 # Legal
 
 '''
-    Copyright (C) 2017 Gitcoin Core
+    Copyright (C) 2018 Gitcoin Core
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU Affero General Public License as published
@@ -136,7 +141,7 @@ Have an ERC20 compatible token that you'ud like to add support for?  Great!
 
 # License
 
-[GNU AFFERO GENERAL PUBLIC LICENSE](./docs/LICENSE)
+[GNU AFFERO GENERAL PUBLIC LICENSE](./LICENSE)
 
 <!-- Google Analytics -->
 <img src='https://ga-beacon.appspot.com/UA-102304388-1/gitcoinco/web' style='width:1px; height:1px;' >

docs/RUNNING_LOCALLY.md

@@ -0,0 +1,93 @@
+# Running Locally without Docker
+
+*Note: This setup method is not recommended. To ensure a consistent environment, please check out the [Docker Setup Guide](RUNNING_LOCALLY_DOCKER.md).
+
+```shell
+brew install libmaxminddb
+git clone https://github.com/gitcoinco/web.git
+cd web/app
+cp app/local.env app/.env
+```
+
+You will need to edit the `app/.env` file with your local environment variables. Look for config items that are marked `# required`.
+
+## Configure Integrations (recommended)
+
+If you plan on using the Github integration, please read the [third party integration guide](THIRD_PARTY_SETUP.md).
+
+## Static Asset Handling (optional)
+
+If you're testing in a staging or production style environment behind a CDN, pass the `DJANGO_STATIC_HOST` environment variable to your django web instance specifying the CDN URL.
+
+For example:
+
+`DJANGO_STATIC_HOST='https://gitcoin.co`
+
+## Setup Database
+
+PostgreSQL is the database used by this application. Here are some instructions for installing PostgreSQL on various operating systems.
+
+[OSX](https://www.moncefbelyamani.com/how-to-install-postgresql-on-a-mac-with-homebrew-and-lunchy/)
+
+[Windows](http://www.postgresqltutorial.com/install-postgresql/)
+
+[Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-16-04)
+
+Once you have Postgres installed and running on your system, enter into a Postgres session.
+
+```shell
+psql
+```
+
+Create the database and a new privileged user.
+
+```sql
+CREATE DATABASE gitcoin;
+CREATE USER gitcoin_user WITH PASSWORD 'password';
+GRANT ALL PRIVILEGES ON DATABASE gitcoin TO gitcoin_user;
+```
+
+Exit Postgres session
+
+```shell
+\q
+```
+
+Update local_settings.py with the connection details.
+
+```python
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.postgresql',
+        'NAME': 'gitcoin',
+        'USER': 'gitcoin_user',
+        'PASSWORD': 'password',
+        'HOST': 'localhost',
+        'PORT': 5432,
+    }
+}
+```
+
+## Startup server
+
+```shell
+virtualenv gcoin
+source gcoin/bin/activate
+pip install -r requirements/base.txt
+pip install -r requirements/dev.txt
+pip install -r requirements/test.txt
+./manage.py migrate
+./manage.py createcachetable
+./manage.py get_prices
+./manage.py runserver 0.0.0.0:8000
+```
+
+Navigate to `http://localhost:8000/`.
+
+## Optional: Import bounty data from web3 to your database
+
+This can be useful if you'd like data to test with:
+
+```shell
+./manage.py sync_geth mainnet 400 99999999999
+```

docs/RUNNING_LOCALLY_DOCKER.md

@@ -0,0 +1,64 @@
+# Running Locally with Docker (Recommended)
+
+```shell
+git clone https://github.com/gitcoinco/web.git
+cd web
+cp app/app/local.env app/app/.env
+```
+
+Navigate to `http://0.0.0.0:8000/`.
+
+*Note: Running `docker-compose logs --tail=50 -f <optional container_name>` will follow all container output in the active terminal window, while specifying a container name will follow that specific container's output. `--tail` is optional.*
+Check out the [Docker Compose CLI Reference](https://docs.docker.com/compose/reference/) for more information.
+
+You will need to edit the `app/.env` file with your local environment variables. Look for config items that are marked `# required`.
+
+## Integration Setup (recommended)
+
+If you plan on using the Github integration, please read the [third party integration guide](THIRD_PARTY_SETUP.md).
+
+## Static Asset Handling (optional)
+
+If you're testing in a staging or production style environment behind a CDN, pass the `DJANGO_STATIC_HOST` environment variable to your django web instance specifying the CDN URL.
+
+For example:
+
+`DJANGO_STATIC_HOST='https://gitcoin.co`
+
+## Startup server
+
+### Running in Detached mode
+
+```shell
+docker-compose up -d --build
+```
+
+### Running in the foreground
+
+```shell
+docker-compose up --build
+```
+
+### Viewing Logs
+
+Actively follow a container's log:
+
+```shell
+docker-compose logs -f web # Or any other container name
+```
+
+View all container logs:
+
+```shell
+docker-compose logs
+```
+
+Navigate to `http://localhost:8000/`.
+
+## Optional: Import bounty data from web3 to your database
+
+This can be useful if you'd like data to test with:
+
+```shell
+docker-compose exec web app/manage.py sync_geth mainnet 400 99999999999
+```

docs/THIRD_PARTY_SETUP.md

@@ -0,0 +1,71 @@
+# Third party integrations
+
+## Setup Github OAuth2 App Integration (Recommended)
+
+Navigate to: [Github - New Application](https://github.com/settings/applications/new) and enter similar values to:
+
+* Enter Application Name: `MyGitcoinApp`
+* Homepage URL: `http://localhost`
+* Application description: `My Gitcoin App`
+* Authorization callback URL: `http://localhost:8000/` (required)
+
+The authorization callback URL should match your `BASE_URL` value in `web/app/app/.env`
+
+Update the `web/app/app/.env` file to include the values provided by Github:
+
+```shell
+GITHUB_CLIENT_ID=xxxx
+GITHUB_CLIENT_SECRET=xxx
+GITHUB_APP_NAME=MyGitcoinApp
+```
+
+## Setup Github User Integration (Recommended)
+
+Navigate to: [Github - New Token](https://github.com/settings/tokens/new)
+At minimum, select `user` scope.
+
+Update the `web/app/app/.env` file to include the values provided by Github:
+
+```shell
+GITHUB_API_TOKEN=xxx
+GITHUB_API_USER=xxx
+```
+
+## Gitcoinbot Installation Instructions
+
+### This integration requires the Github OAuth2 App Integration
+
+Navigate to: [Gitcoinbot Github App](https://github.com/apps/gitcoinbot)
+Copy the application ID found on the page as the `GITCOINBOT_APP_ID` environment variable.
+
+The following environment variables must be set for gitcoinbot to work correctly:
+
+```shell
+GITHUB_API_USER=gitcoinbot  # Github Profile name of the bot. Defaults to: gitcoinbot
+GITCOINBOT_APP_ID=APP_ID_FROM_ABOVE  # Defaults to empty.
+GITCOIN_BOT_CERT_PATH=RELATIVE_PATH_TO_CERT_FILE  # Defaults to empty.
+```
+
+#### Example
+
+```shell
+GITHUB_API_USER=gitcoinbot  # Github Profile name of the bot. Defaults to: gitcoinbot
+GITCOINBOT_APP_ID=7735  # Gitcoin Bot App ID
+GITCOIN_BOT_CERT_PATH=app/gitcoin_bot_secret.pem  # If pem file is located at web/app/app/gitcoin_bot_secret.pem
+```
+
+Aside from these environment variables, the settings page of the gitcoin bot application must have the correct url for webhook events to post to. It should be set to `https://gitcoin.co/payload` based on urls.py line 131.
+
+After running the migrations and deploying the gitcoin.co website, gitcoinbot will begin to receive webhook events from any repository that it is installed into. This application will then parse through the comments and respond if it is called with @gitcoinbot + registered action call.
+
+## Rollbar Integration
+
+Error tracking is entirely optional and primarily for internal staging and production tracking.
+If you would like to track errors of your local environment, setup an account at: [Rollbar.com](https://rollbar.com)
+
+Once you have access to your project access tokens, you can enable rollbar error tracking for both the backend and frontend by adding the following environment variables to `web/app/app/.env`:
+
+```shell
+ROLLBAR_CLIENT_TOKEN=post_client_item
+ROLLBAR_SERVER_TOKEN=post_server_item
+```