Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@nlaz
nlaz committed Mar 1, 2019
1 parent 0007be1 commit c026f0a
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 36 deletions.
26 changes: 13 additions & 13 deletions README.md
View file
Expand Up @@ -2,17 +2,17 @@

This is a hackathon boilerplate for new Flask web applications created by [Major League Hacking](https://github.com/MLH). It is for hackers looking to get started quickly on a new hackathon project using the Flask microframework.

* [Installation Guide](#installation-guide) - How to get started with a new Flask app
* [User Guide](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/docs/USER_GUIDE.md) - How to develop apps created with this starter project
* [Contributing Guide](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/docs/CONTRIBUTING.md) - How to contribute to the project
- [Installation Guide](#installation-guide) - How to get started with a new Flask app
- [User Guide](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/docs/USER_GUIDE.md) - How to develop apps created with this starter project
- [Contributing Guide](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/docs/CONTRIBUTING.md) - How to contribute to the project

# <a name='installation-guide'>Installation Guide</a>

This project requires the following tools:

* Python - The programming language used by Flask.
* PostgreSQL - A relational database system.
* Virtualenv - A tool for creating isolated Python environments.
- 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/).

Expand Down Expand Up @@ -66,7 +66,7 @@ You replace the GitHub credentials here and update the database URL. Learn more
Now we're ready to start our server which is as simple as:

```
(venv) flask run
(venv) $ flask run
```

Open http://localhost:5000 to view it in your browser.
Expand All @@ -76,12 +76,12 @@ You will see the build errors and warnings in the console.

# What's Included?

* [Flask](http://flask.pocoo.org/) - A microframework for Python web applications
* [Flask Blueprints](http://flask.pocoo.org/docs/1.0/blueprints/) - A Flask extension for making modular applications
* [Flask-SQLAlchemy](http://flask-sqlalchemy.pocoo.org/2.3/) - A Flask extension that adds ORM support for your data models.
* [Werkzeug](http://werkzeug.pocoo.org/) - A Flask framework that implements WSGI for handling requests.
* [Bootstrap 4](https://getbootstrap.com/) - An open source design system for HTML, CSS, and JS.
* [Jinja2](http://jinja.pocoo.org/docs/2.10/) - A templating language for Python, used by Flask.
- [Flask](http://flask.pocoo.org/) - A microframework for Python web applications
- [Flask Blueprints](http://flask.pocoo.org/docs/1.0/blueprints/) - A Flask extension for making modular applications
- [Flask-SQLAlchemy](http://flask-sqlalchemy.pocoo.org/2.3/) - A Flask extension that adds ORM support for your data models.
- [Werkzeug](http://werkzeug.pocoo.org/) - A Flask framework that implements WSGI for handling requests.
- [Bootstrap 4](https://getbootstrap.com/) - An open source design system for HTML, CSS, and JS.
- [Jinja2](http://jinja.pocoo.org/docs/2.10/) - A templating language for Python, used by Flask.

# Code of Conduct

Expand Down
49 changes: 26 additions & 23 deletions docs/USER_GUIDE.md
View file
Expand Up @@ -10,7 +10,6 @@ This project simply provides the boilerplate to get started with a new Flask app

Even if you are not using it for a hackathon, it should save you time getting started building and learning Flask development.


## Starting the app

**Step 1. Clone the code into a fresh folder**
Expand Down Expand Up @@ -101,17 +100,20 @@ mlh-hackathon-flask-starter/
├── services/
│ └── github.py
├── static/
│ ├── vendor/
│ └── style.css
│ ├── css/
│ ├── img/
│ └── favicon.ico
├── templates/
│ ├── github/
│ └── home/
│ ├── home/
│ ├── layouts/
│ ├── partials/
│ └── tutorial/
├── app.py
├── extensions.py
└── settings.py
```

The core of the Flask app is contained within the `app` directory. It contains `app.py`, the code to create and run the app, `/views`, handles all the endpoints and business logic, `/models`, handles all the features for the data models like users, `/templates`, contains the templates for [Jinja](http://jinja.pocoo.org/docs/2.10/)-based layouts, and `/static`, contains all the static assets. You can learn more about [the structure of Flask apps here](http://flask.pocoo.org/docs/1.0/tutorial/layout/).
The core of the Flask app is contained within the `app` directory. It contains `app.py`, the code to create and run the app, `/controllers`, handles all the endpoints and business logic, `/models`, handles all the features for the data models like users, `/templates`, contains the templates for [Jinja](http://jinja.pocoo.org/docs/2.10/)-based layouts, and `/static`, contains all the static assets. You can learn more about [the structure of Flask apps here](http://flask.pocoo.org/docs/1.0/tutorial/layout/).

## Flask Development

Expand All @@ -123,7 +125,7 @@ This project uses GitHub OAuth to handle user authentication. Meaning a new user

The tradeoff is that you have to go through the [GitHub OAuth flow](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/) with your application. This process is pretty simple:

1. Users clicked **Sign in with GitHub**.
1. Users clicked **Login with GitHub**.
2. Users are redirected to GitHub.com to request their identity.
3. Users grant permission to your app and are redirected back to your site.
4. Your app sends a request for the user access token.
Expand All @@ -144,35 +146,38 @@ $ python
... Prints out results from GitHub
```

These type of requests can be made inside of your controllers to fetch and store data for your application. For example, you might make a request to GitHub's API and display it [directly in HTML](/github). Depending on your needs, you can also store this data to your database to use later.
These type of requests can be made inside of your controllers to fetch and store data for your application. For example, you might make a request to GitHub's API and display it directly in HTML. Depending on your needs, you can also store this data to your database to use later.

To make things simple, we provide a service for GitHub-related requests, which will handle user authentication. Here is that [service in action](https://github.com/MLH/github-hackathon-starter/blob/master/app/views/github.py).
To make things simple, we provide a service for GitHub-related requests, which will handle user authentication. Here is that [service in action](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/app/controllers/github.py).

## Static Files

Flask automatically adds a `static` view that serves files located in the `/static` folder. This folder is typically reserved for static files like CSS stylesheets, JavaScript files, images, or other assets. The folder currently has some default files to get started.

```
static/
├── favicon.ico
├── color.css
├── logo.png
└── style.css
├── css/
| ├── color.css
| └── style.css
├── img/
| └── logo.png
└── favicon.ico
```

The `style.css` file is a good place to add custom CSS. Add any of your CSS or JavaScript in this folder.

## Saving to a Database

### Using Postgres

Flask does not come with a database layer by default. It is designed to have a database added later. You can add your own preferred database type to the project if needed. We like the PostgreSQL database which is easy to deploy with Heroku.

To use PostgreSQL with your project, you will need to [install it locally](https://wiki.postgresql.org/wiki/What's_new_in_PostgreSQL_9.4).

1. Install [Postgres locally](https://wiki.postgresql.org/wiki/What's_new_in_PostgreSQL_9.4)*
1. Install [Postgres locally](https://wiki.postgresql.org/wiki/What's_new_in_PostgreSQL_9.4)\*
2. Make sure Postgres is running locally.
3. Replace the `DATABASE_URL` variable in `.env` with your database.
* i.e. `DATABASE_URL=postgresql://localhost:5432/mlh-hackathon-flask-starter`
- i.e. `DATABASE_URL=postgresql://localhost:5432/mlh-hackathon-flask-starter`

\* A simple way for Mac OS X users to install Postgres is using [Postgres.app](https://postgresapp.com/).

Expand All @@ -195,14 +200,15 @@ This project uses a GitHub OAuth app for Authentication and uses GitHub's API. T
1. Register an account on Github.com.
2. Visit the [GitHub OAuth apps page](https://github.com/settings/developers).
3. Create a new OAuth app.
* Enter an application name and a homepage URL.
* Add callback URL, use http://localhost:5000/ for local development.
* Click 'Register application'.
- Enter an application name and a homepage URL.
- 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:

```
Expand All @@ -216,7 +222,6 @@ The `DATABASE_URL` variable is the path to your database system. This is where y

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'
Expand All @@ -225,7 +230,6 @@ 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

### Deploy to Heroku
Expand All @@ -242,7 +246,6 @@ Alternatively, you can use this button to create a new application on Heroku:

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/MLH/mlh-hackathon-flask-starter)


# Support

If you are having problems running the project or getting it to work, check the [issue tracker](https://github.com/MLH/mlh-hackathon-flask-starter/issues) for any related issues. It might also have the solution to your issue. If an issue doesn't already exist, feel free to open a new issue. We will try to respond as quickly as possible.
Expand Down

0 comments on commit c026f0a

Please sign in to comment.