Skip to content
Permalink
Browse files

Update documentation and fix links

  • Loading branch information...
nlaz committed Feb 13, 2019
1 parent 617a11e commit f088237cf38dc3d004aa299030c9ec4ed57fe83a
Showing with 58 additions and 21 deletions.
  1. +4 −5 README.md
  2. +1 −1 app.json
  3. +4 −2 app/templates/home/index.html
  4. +49 −13 docs/USER_GUIDE.md
@@ -3,8 +3,8 @@
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](/user-guide) - How to develop apps created with this starter project
* [Contributing Guide](/contributing) - How to contribute to the project
* [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>

@@ -25,7 +25,6 @@ $ git clone https://github.com/MLH/mlh-hackathon-flask-starter.git
$ cd mlh-hackathon-flask-starter
```


**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).
@@ -87,8 +86,8 @@ You will see the build errors and warnings in the console.

# Code of Conduct

We enforce a Code of Conduct for all maintainers and contributors of this Guide. Read more in [CONDUCT.md](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/starter/docs/CONDUCT.md).
We enforce a Code of Conduct for all maintainers and contributors of this Guide. Read more in [CONDUCT.md](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/docs/CONDUCT.md).

# License

The Hackathon Starter Kit is open source software [licensed as MIT](https://github.com/nlaz/github-hackathon-starter/blob/master/LICENSE.md).
The Hackathon Starter Kit is open source software [licensed as MIT](https://github.com/MLH/github-hackathon-starter/blob/master/LICENSE.md).
@@ -1,7 +1,7 @@
{
"name": "MLH Hackathon Flask Starter",
"description": "A hackathon starting point for new Flask applications",
"repository": "https://github.com/nlaz/mlh-hackathon-flask-starter.git",
"repository": "https://github.com/MLH/mlh-hackathon-flask-starter.git",
"logo": "https://avatars1.githubusercontent.com/u/5752708?s=100",
"keywords": ["python", "flask"]
}
@@ -3,12 +3,14 @@
{% block header %}
<div class='bg-gray-light border-bottom text-gray-dark' style='overflow:hidden;'>
<div class='container position-relative py-5'>
<div class='py-5 my-5'>
<div class='py-md-5 my-lg-5'>
<h1 class='display-5 mb-1 text-blue-light'>Hackathon Flask Starter</h1>
<h2 class='lead text-gray-light'>Presented by GitHub & MLH.</h2>
<div class='position-absolute d-flex align-items-center' style='top:0;right:-100px;max-width:600px;'>

<div class='d-none position-absolute d-lg-flex align-items-center' style='top:0;right:-100px;max-width:600px;'>
<img class='w-100' src="{{ url_for('static', filename='img/labtocat.png') }}" />
</div>

</div>
</div>
</div>
@@ -2,7 +2,7 @@

This is the User Guide for the Hackathon Starter Kit. Here you will find additional documentation and guides on how to use the project.

If you think we are missing something or you have ideas for more guides that should be on this page, [let us know](mailto:hi@mlh.io) or [contribute some](/contributing)!
If you think we are missing something or you have ideas for more guides that should be on this page, [let us know](mailto:hi@mlh.io) or [contribute some](https://github.com/MLH/mlh-hackathon-flask-starter/blob/master/docs/CONTRIBUTING.md)!

## How It Works

@@ -13,26 +13,62 @@ Even if you are not using it for a hackathon, it should save you time getting st

## Starting the app

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.
**Step 1. Clone the code into a fresh folder**

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.
```
$ git clone https://github.com/MLH/mlh-hackathon-flask-starter.git
$ cd mlh-hackathon-flask-starter
```

**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).

```
$ virtualenv venv
$ source venv/bin/activate
```

Next, we need to install the project dependencies, which are listed in `requirements.txt`.

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

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

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
```

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.

**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
```

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.

### `flask run`

Runs the app in development mode. Requires the `FLASK_APP` and `FLASK_ENV` variables to be set.
@@ -110,7 +146,7 @@ $ python

These type of requests can be made inside of your views 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.

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/nlaz/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/github-hackathon-starter/blob/master/app/views/github.py).

## Static Files

@@ -204,7 +240,7 @@ Heroku is an easy way for developers to deploy their application. To deploy to H

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/nlaz/mlh-hackathon-flask-starter)
[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/MLH/mlh-hackathon-flask-starter)


# Support

0 comments on commit f088237

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