Skip to content
Permalink
Browse files

Update README.md and support python 2

  • Loading branch information...
niko niko
niko authored and niko committed Feb 12, 2019
1 parent b8be3bc commit 897f54d7d0da297bd5bd00109bccd6968960cad3
Showing with 82 additions and 55 deletions.
  1. +3 −6 .env.example
  2. +2 −0 .flaskenv
  3. +28 −31 README.md
  4. +2 −2 app/app.py
  5. +2 −0 app/models/user.py
  6. +8 −7 app/services/github.py
  7. +1 −1 app/settings.py
  8. +6 −5 app/views/auth.py
  9. +1 −0 app/views/github.py
  10. +2 −1 app/views/public.py
  11. +27 −2 docs/USER_GUIDE.md
@@ -1,7 +1,4 @@
# Sample environment variables file.
FLASK_APP=app/app.py
FLASK_ENV=development
DATABASE_URL="sqlite:////tmp/dev.db"
SECRET_KEY="octocat"
GITHUB_CLIENT_ID="<INSERT_CLIENT_ID>"
GITHUB_CLIENT_SECRET="<INSERT_CLIENT_SECRET>"
DATABASE_URL="[INSERT_DATABASE_URL]"
GITHUB_CLIENT_ID="[INSERT_CLIENT_ID]"
GITHUB_CLIENT_SECRET="[INSERT_CLIENT_SECRET]"
@@ -0,0 +1,2 @@
FLASK_APP=app/app.py
FLASK_ENV=development
@@ -10,69 +10,66 @@ This is a hackathon boilerplate for new Flask web applications created by [Major

This project requires the following tools:

* Python ([3.4](https://www.python.org/downloads/)) - The programming language used by Flask.
* PostgreSQL ([9.4](https://wiki.postgresql.org/wiki/What's_new_in_PostgreSQL_9.4)) - A relational database system.
* Python - The programming language used by Flask.
* PostgreSQL - A relational database system.
* Virtualenv - A tool for creating isolated Python environments.

To get started, install Python and Postgres on your local computer, if you don't have them already. A simple way for Mac OS X users to install Postgres is using [Postgres.app](https://postgresapp.com/). You can optionally use another database system instead of Postgres, like [SQLite](http://flask.pocoo.org/docs/1.0/patterns/sqlite3/).

## Installation
## Getting Started

**1. Clone this repository to your local computer.**
**Step 1. Clone the code into a fresh folder: `git clone https://github.com/MLH/mlh-hackathon-flask-starter.git`**

```
$ git clone https://github.com/MLH/mlh-hackathon-flask-starter.git
$ cd mlh-hackathon-flask-starter
```

**2. Create and activate a [virtual environment](http://flask.pocoo.org/docs/1.0/installation/#virtual-environments).**
**Step 2. Create a Virtual Environment and install Dependencies.**

Create a new Virtual Environment for the project and activate it. If you don't have the `virtualenv` command yet, you can find installation [instructions here](https://virtualenv.readthedocs.io/en/latest/). Learn more about [Virtual Environments](http://flask.pocoo.org/docs/1.0/installation/#virtual-environments).

```
$ python3 -m venv venv
$ . venv/bin/activate
$ virtualenv venv
$ source venv/bin/activate
```

**3. Install Flask dependencies using `pip`.**
Next, we need to install the project dependencies, which are listed in `requirements.txt`.

```
$ pip install -r requirements.txt
(venv) $ pip install -r requirements.txt
```

**Step 3: Create an app on GitHub**

## Starting the app
Head over to [GitHub OAuth apps](https://github.com/settings/developers) and create a new OAuth app. Name it what you like but you'll need to specify a callback url, which should be something like:

```
https://localhost:5000/auth/callback/github
```

You can run your application from your terminal using the `flask` command. To run the app locally, you need to tell Flask where to find your application, then run it in development mode.
The default port for Flask apps is `5000`, but you may need to update this if your setup uses a different port or if you're hosting your app somewhere besides your local machine.

Development mode makes it easier to make changes to your application. It includes an interactive debugger and will restart the server whenever you make changes to the code.
**Step 4: Update environment variables and run the Server.**

For Linux and Mac:
Create a new file named `.env` by duplicating `.env.sample`. Update the new file with the GitHub credentials. It should look similar to this:

```
export FLASK_APP=app/app.py
export FLASK_ENV=development
flask run
# .env file
DATABASE_URL="[INSERT_DATABASE_URL]"
GITHUB_CLIENT_ID="[INSERT_CLIENT_ID]"
GITHUB_CLIENT_SECRET="[INSERT_CLIENT_SECRET]"
```

For Windows Powershell, use `$env:` instead of `export`:
You replace the GitHub credentials here and update the database url. Learn more about the required [Environment Variables here](#environment-variables).

Now we're ready to start our server which is as simple as:

```
$env:FLASK_APP = 'app/app.py'
$env:FLASK_ENV = 'development'
flask run
(venv) flask run
```

### `flask run`

Runs the app in development mode. Requires the `FLASK_APP` and `FLASK_ENV` variables to be set.
Open http://localhost:5000 to view it in your browser.

The app will automatically reload if you make changes to the code.
You will see the build errors and warnings in the console.

### `pip install`

Installs a Python package for your application. Used to add new functionality to the project.

# What's Included?

* [Flask](http://flask.pocoo.org/) - A microframework for Python web applications
@@ -1,8 +1,8 @@
import os

from flask import Flask, render_template
from app import settings, views, models
from app.extensions import db, markdown
from . import settings, views, models
from extensions import db, markdown

project_dir = os.path.dirname(os.path.abspath(__file__))

@@ -14,6 +14,7 @@ def __init__(self, username, avatar_url, github_id):
self.avatar_url = avatar_url
self.github_id = github_id

@staticmethod
def find_or_create_from_token(access_token):
data = GitHub.get_user_from_token(access_token)

@@ -27,6 +28,7 @@ def find_or_create_from_token(access_token):

return instance

@staticmethod
def find_or_create_from_token(access_token):
data = GitHub.get_user_from_token(access_token)

@@ -32,13 +32,6 @@ def get_token(self, code):
data = requests.post(token_url, params=params, headers=headers).json()
return data.get('access_token', None)

def get_user_from_token(access_token):
"""Fetch user data using the access token."""
url = api_url + '/user'
params = { 'access_token': access_token }

return requests.get(url, params=params).json()

def get(self, route_url, params = {}):
url = api_url + route_url
params['access_token'] = self.access_token
@@ -56,3 +49,11 @@ def delete(self, route_url, params = {}):
params['access_token'] = self.access_token

return requests.delete(url, params=params)

@staticmethod
def get_user_from_token(access_token):
"""Fetch user data using the access token."""
url = api_url + '/user'
params = { 'access_token': access_token }

return requests.get(url, params=params).json()
@@ -8,7 +8,7 @@
ENV = os.getenv('FLASK_ENV', default='production')
DEBUG = ENV == 'development'
SQLALCHEMY_DATABASE_URI = os.getenv('DATABASE_URL')
SECRET_KEY = os.getenv('SECRET_KEY')
SECRET_KEY = os.getenv('SECRET_KEY', default='octocat')
GITHUB_CLIENT_ID = os.getenv('GITHUB_CLIENT_ID')
GITHUB_CLIENT_SECRET = os.getenv('GITHUB_CLIENT_SECRET')
SQLALCHEMY_TRACK_MODIFICATIONS = False
@@ -1,3 +1,4 @@
# -*- coding: utf-8 -*-
import functools, json, requests

from flask import flash, redirect, render_template, request
@@ -9,22 +10,22 @@

blueprint = Blueprint('auth', __name__, url_prefix='/auth')

github = GitHub(GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET)

@blueprint.route('/github/login')
@blueprint.route('/login/github')
def githubLogin():
github = GitHub(GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET)
return redirect(github.authorization_url(scope='public_repo'))

@blueprint.route('/github/callback', methods=('GET', 'POST'))
@blueprint.route('/callback/github', methods=('GET', 'POST'))
def githubCallback():
if 'code' not in request.args:
return '', 500

# Fetch user from GitHub OAuth and store in session
github = GitHub(GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET)
access_token = github.get_token(request.args['code'])

if access_token is None:
flash('Could not authorize your request. Please try again.')
flash('Could not authorize your request. Please try again.', 'danger')
return '', 404

user = User.find_or_create_from_token(access_token)
@@ -1,3 +1,4 @@
# -*- coding: utf-8 -*-
from flask import redirect, render_template, request
from flask import Blueprint, flash, url_for, session

@@ -1,3 +1,4 @@
# -*- coding: utf-8 -*-
from flask import Blueprint, render_template

from app.extensions import markdown
@@ -14,7 +15,7 @@ def index():
@blueprint.route('/user-guide')
def user_guide():
with open('docs/USER_GUIDE.md', 'r') as input_file:
text = input_file.read()
text = input_file.read().decode('utf-8')
content = markdown.render(text)
return render_template('home/index.html', body=content)

@@ -163,8 +163,33 @@ This project uses a GitHub OAuth app for Authentication and uses GitHub's API. T
* Add callback URL, use http://localhost:5000/ for local development.
* Click 'Register application'.
4. Add your GitHub credentials to your environment variables in `.env`.
* Replace `<INSERT_CLIENT_ID>` with your GitHub Client ID.
* Replace `<INSERT_CLIENT_SECRET>` with your GitHub Client Secret.
* Replace `[INSERT_CLIENT_ID]` with your GitHub Client ID.
* Replace `[INSERT_CLIENT_SECRET]` with your GitHub Client Secret.

## <a name='environment-variables'>Environment Variables</a>
To run the project, you need to configure the application to run locally. This will require updating a set of environment variables specific to your environment. Create a new file named `.env` by duplicating `.env.sample`. Update the new file with the GitHub credentials. It should look similar to this:

```
# .env file
SECRET_KEY="octocat"
DATABASE_URL="[INSERT_DATABASE_URL]"
GITHUB_CLIENT_ID="[INSERT_CLIENT_ID]"
GITHUB_CLIENT_SECRET="[INSERT_CLIENT_SECRET]"
```

The `DATABASE_URL` variable is the path to your database system. This is where you can add the url to your PostgreSQL.

The `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` variables are the app credentials from your [GitHub OAuth app](https://github.com/settings/developers).


```
# .flaskenv file
FLASK_APP='app/app.py'
FLASK_ENV='development'
```

The `FLASK_APP` and `FLASK_ENV` variables are needed for running the application locally. The `SECRET_KEY` variable is used to manage the server sessions.


## Deployment

0 comments on commit 897f54d

Please sign in to comment.
You can’t perform that action at this time.