Revised Readme

README.md

@@ -1,3 +1,5 @@
+# TODO: Add important files table from Django Readme
+
 # Flask-VueJs-Template
 
 [![Build Status](https://travis-ci.org/gtalarico/flask-vuejs-template.svg?branch=master)](https://travis-ci.org/gtalarico/flask-vuejs-template)
@@ -10,45 +12,48 @@ _Flask + Vue.js Web Application Template_
 [Live Demo](https://flask-vuejs-template.herokuapp.com/#/api)
 
 ## Features
-* Minimal Flask App with modular Config
+* Minimal Flask 1.0 App
 * [Flask-RestPlus](http://flask-restplus.readthedocs.io) API with class-based secure resource routing
 * Starter [PyTest](http://pytest.org) test suite
-* [vue-cli 3](https://github.com/vuejs/vue-cli/blob/dev/docs/README.md) with Babel and ESlint.
-* [Vuex](https://vuex.vuejs.org/) for state management
+* [vue-cli 3](https://github.com/vuejs/vue-cli/blob/dev/docs/README.md)
+* [Vuex](https://vuex.vuejs.org/)
 * [Vue Router](https://router.vuejs.org/)
 * [Axios](https://vuex.vuejs.org/) for backend communication
 * Sample Vue [Filters](https://vuejs.org/v2/guide/filters.html)
-* Heroku Configuration with one-click deployment
+* Heroku Configuration with one-click deployment + Gunicorn
 
 ## Template Structure
 
-The template uses Flask & Flask-RestPlus to create a REST style API,
+The template uses Flask & Flask-RestPlus to create a minimal REST style API,
 and let's VueJs + vue-cli handle the front end and asset pipline.
+Data from the python server to the Vue application is passed by making Ajax requests.
 
-### Blueprints
-
-The Flask application is setup with with two blueprints:
-
+### Application Structure
 
-#### Api Blueprint
+#### Rest Api
 
-Uses Flask-RestPlus to serve resources at the `/api` endpoint.
-Flask-RestPlus can be discarded if you prefer standard view functions routing.
+The Api is served using a Flask blueprint at `/api/` using Flask RestPlus class-based
+resource routing.
 
-#### Client Blueprint
+#### Client Application
 
 A simple Flask view is used to serve the entry point into the Vue application at the root endpoint `/`
-The template uses vue-cli 3 and assumes Vue.js & Webpack will manage front-end resources and assets,
-so it does overwrite template delimiter.
+The template uses vue-cli 3 and assumes Vue.js & Webpack will manage front-end resources and assets, so it does overwrite template delimiter - it serves static
+files as generated by vue cli + webpack
 
 The Vue instance is preconfigured with Filters, Vue-Router, Vuex; each of these can easilly removed if they are not desired.
 
 ## Installation
 
 ##### Before you start
 
-* Make sure node + npm are installed (tested with npm v5.6)
-* Python 3 is installed (tested with 3.6)
+Before getting started you should have the following installed and running:
+
+- [X] Yarn - [instructions](https://yarnpkg.com/en/docs/install#mac-stable)
+- [X] Vue Cli 3 - [instructions](https://cli.vuejs.org/guide/installation.html)
+- [X] Python 3
+- [X] Pipenv (optional)
+- [X] Heroku Cli (if deploying to Heroku)
 
 ##### Template and Dependencies
 
@@ -58,79 +63,78 @@ The Vue instance is preconfigured with Filters, Vue-Router, Vuex; each of these
 	$ git clone https://github.com/gtalarico/flask-vuejs-template.git
 	```
 
-* Create a [virtual enviroment](https://packaging.python.org/tutorials/managing-dependencies/#managing-dependencies) (highly recommended)
-
-* Install Python dependencies using pip or pipenv from the project directory:
+* Setup virtual environment, install dependencies, and activate it:
 
-	`$ pipenv install` or `pip install -r requirements.txt`
+	```
+	$ pipenv install --dev
+	$ pipenv shell
+	```
 
-* Install npm dependencies
+* Install JS dependencies
 
 	```
-	$ cd app/client/vue_app
-	$ npm install
+	$ yarn install
 	```
 
 
 ## Development Server
 
-While it's possible to use Flask to serve the vue app and the rest api, it is less than ideal as each change in client code would required a full rebuild and reload. Instead, we will use flask the serve the api endpoints, but we will serve the client app using the vue-cli dev server.
-This combination allows you have both your backend python files and the Vue appplication files auto-reload on save.
-
-This template also includes a few functions to help us manage the 2 servers.
+Run Flask Api development server:
 
-This enables us to take advantage of Hot Module Replacement (HMR) and ESlint.
-I think it is a small price to pay for the amount of time saved by HMR alone.
-
-##### Api Server
+```
+$ python run.py
+```
 
-From the root directory run:
+From another tab in the same directory, start the webpack dev server:
 
 ```
-$ python -m app serve_api
+$ yarn serve
 ```
 
-This will start the flask development server on `localhost:5000` and will respond to all requests on `/api.`.
-This command is the same as running `python run.py`
+The Vuejs application will be served from `localhost:8080` and the Flask Api
+and static files will be served from `localhost:5000`.
 
-##### Client Server
+The dual dev server setup allows you to take advantage of
+webpack's development server with hot module replacement.
+Proxy config in `vue.config.js` is used to route the requests
+back to Flask's Api on port 5000.
 
-Start another terminal window, and from the same directory run:
+If you would rather run a single dev server, you can run Flask's
+development server only on `:5000`, but you have to build build the Vue app first
+and the page will not reload on changes.
 
 ```
-$ python -m app serve_client
+$ yarn build
+$ python run.py
 ```
 
-This will launch your browser and server the Vue application on `localhost:8080`. T
-he vue app will hit `localhost:5000` to fetch resources.
-
-This combination allows you have both your backend python files, as well as the Vue app files autoreload on each file save.
-
 
 ## Production Server
 
-The production server uses Gunicorn to serve the entire application.
-This template is configured to work with Heroku out of the box - just make sure you run `npm run build` before pushing it to your Heroku repository.
+This template is configured to work with Heroku + Gunicorn and it's pre-configured
+to have Heroku build the application before releasing it.
 
-* Build your Vue Application:
-```
-$ python app build
-```
-This commands is a shorcut for cd-ing into `/app/client/vue_app` and running `$ npm run build`.
-
-* Commit your code
-
-* Setup your heroku app:
+Here are the commands we need to run to get things setup on the Heroku side:
 
 	```
-	$ heroku apps:create flask-vuejs-template
-	$ heroku config:set FLASK_CONFIG=Production
-	$ heroku config:set SECRET=SECRETKEY
-	$ heroku git:remote --app flask-vuejs-template
+	$ heroku apps:create flask-vuejs-template-demo
+	$ heroku git:remote --app flask-vuejs-template-demo
+	$ heroku buildpacks:add --index 1 heroku/nodejs
+	$ heroku buildpacks:add --index 2 heroku/python
+	$ heroku addons:create heroku-postgresql:hobby-dev
+	$ heroku config:set FLASK_ENV=production
+	$ heroku config:set FLASK_SECRET=SuperSecretKey
+
+	$ git push heroku
 	```
-* Push your application to heroku:
 
-	```$ git push heroku```
+Heroku's nodejs buidlpack will handle install for all the dependencies from the `packages.json` file.
+It will then trigger the `postinstall` command which calls `yarn build`.
+This will create the bundled `dist` folder which will be served by whitenoise.
+
+The python buildpack will detect the `pipfile` and install all the python dependencies.
+
+The `Procfile` will run Django migrations and then launch Django'S app using gunicorn, as recommended by heroku.
 
 ### Heroku deployment - One Click Deploy