Skip to content
This repository was archived by the owner on Oct 7, 2019. It is now read-only.

Commit b570569

Browse files
gasscgassc
committed
updated docs
1 parent 574a6a1 commit b570569

File tree

3 files changed

+82
-49
lines changed

3 files changed

+82
-49
lines changed

‎README.md

+76-30
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,46 @@
22

33
A simple map-based application for estimating the power potential of microhydropower installations.
44

5-
## Software
5+
## Architecture Overview
66

77
The Bard Microhydropower Calculator is built with Python-Flask, Leaflet, Esri-Leaflet, Bootstrap, and jQuery. Data and Geoprocessing services are from the Esri Living Atlas in ArcGIS Online (AGOL).
88

9-
### Development Quickstart
9+
Python Flask provides a server-side framework for assembling the web application from templates and assets. Since this is a single page app, it doesn't have much to do in that regard. Rather, its role is primarily to serve as a proxy for authenticating into secured Esri ArcGIS Online (AGOL) resources. It retrieves an AGOL authentication token on page load and returns it to the client side code (javascript), where it is used to make calls to elevation and other data services from Esri.
10+
11+
On the front-end:
12+
13+
* Bootstrap and jQuery provides the stack for the mobile-adaptive layout
14+
* Leaflet is used for the map
15+
* Esri-Leaflet helps utilize Esri services in conjunction with the Leaflet map
16+
17+
Front-end business logic is written in javascript with only jQuery. Javascript and CSS compliation and bundling is being handled by GulpJS and Browserify.
18+
19+
## Development
20+
21+
### Configuration (`config.py`)
22+
23+
The application requires a few global configuration variables to be set, mainly to enable access to 3rd-party services.
24+
25+
See `app/config.py` for more information.
26+
27+
_to be completed._
28+
29+
#### ArcGIS Application Registration
30+
31+
* Esri Application ID
32+
* Esri Application Secret
33+
34+
#### Mapbox Token
35+
36+
* Token
1037

11-
This application requires Python 3.4 or later. Client-side javascript dependencies are included with the repository, so no javascript build system (e.g., Node/NPM) is currently necessary. However that _should_ change in the future; more on that later.
38+
### Quickstart
1239

13-
This quickstart assumes you have:
40+
To develop this, you must have installed:
1441

15-
* a working installation of Python 3.4+,
16-
* you can call `python` and `pip` or (`python -m pip`) from the command line
42+
* Python 3.4+, and you can call `python` and `pip` or (`python -m pip`) from the command line
43+
* Node/NPM and you can call `node` and `npm` from the command line
44+
* GulpJS installed (available via `npm`)
1745
* `git` installed, also available from the command line.
1846

1947
1. Clone the repository.
@@ -23,7 +51,7 @@ git clone https://github.com/civicmapper/bard-hydropower
2351
cd bard-hydropower
2452
```
2553

26-
1. Initialize a Python virtual environment and install dependencies with Python `pipenv`:
54+
1. Initialize a Python virtual environment and install Python dependencies with Python `pipenv`:
2755

2856
If you don't have `pipenv` (and you won't with an out-of-the-box python installation)
2957

@@ -39,52 +67,70 @@ pipenv install
3967

4068
...to install dependencies, and then:
4169

70+
1. Run a basic development server:
71+
4272
```shell
43-
pipenv shell
73+
pipenv shell python run.py
4474
```
4575

46-
...to activate the virtual environment.
76+
Navigate to [http://localhost:5000](http://localhost:5000) to see the site.
77+
78+
Note that this only serves up compiled client-side code built stored with the repository. It does not run the client-side build tasks.
79+
80+
You can kill this development server by pressing `ctrl-c` in the command line.
81+
82+
### Client-Side Development
4783

48-
1. Run the development server:
84+
(assuming you've installed Python dependencies above)
4985

50-
Within the `pipenv shell`:
86+
1. Install javascript dependencies
87+
88+
In the repository root:
5189

5290
```shell
53-
python run.py
91+
npm install
5492
```
5593

56-
Navigate to [http://localhost:5000](http://localhost:5000) to see the site.
94+
This will download and install a whole lot of javascript in a `node_modules` folder.
5795

58-
### Architecture
96+
2. Run a browser-synced development server
5997

60-
Python Flask provides a server-side framework for assembling the web application from templates and assets. Since this is a single page app, it doesn't have much to do in that regard. Rather, its role is primarily to serve as a proxy for authenticating into secured Esri ArcGIS Online (AGOL) resources. It retrieves an AGOL authentication token on page load and returns it to the client side code (javascript), where it is used to make calls to elevation and other data services from Esri.
98+
```shell
99+
gulp watch
100+
```
61101

62-
On the front-end:
102+
This does a bunch of things:
63103

64-
* Bootstrap and jQuery provides the stack for the mobile-adaptive layout
65-
* Leaflet is used for the map
66-
* Esri-Leaflet helps utilize Esri services in conjunction with the Leaflet map
104+
* it compiles and bundles `js` files from the `src` and `node_modules` directory, and puts them in the the `app/static` directory (where the application wants them to be)
105+
* it does the same with `css` files
106+
* it copies assets from certain `js` modules to the `app/static/assets` directory,
107+
* it fires up the Python-Flask application and its development web server for you (runs `pipenv shell python run.py`)
108+
* it opens up your default browser and loads the page.
67109

68-
Front-end business logic is written in javascript with only jQuery. Javascript bundling for _business-logic only_ is being handled by the Flask plugin Flask-Assets.
110+
3. Develop and see changes as they happen
69111

70-
NOTE: Currently, all javascript (including 3rd party dependencies like Leaflet) are being loaded through standard `<script>` tags in the `html`. In the future 3rd-party dependencies should installed with `npm`, explicitly imported into the business logic scripts, and all should be bundled with a task runner like Gulp, Webpack, or Rollup.
112+
With #2 complete, when you change code in the `src` folder, the browser will either:
71113

72-
### Configuration (`config.py`)
114+
* live reload (inserting your changes into the page)
115+
* refresh automatically (if it needs to reload an entire script or asset again)
73116

74-
#### ArcGIS Application Registration
117+
## Build
118+
119+
Use `gulp build` from the command line to compile source code and copy assets in the `app` folder. Once built, only the `app` folder (and its contents) and `application.py` script are required for running the web application in production.
120+
121+
Make sure your `config.py` `DEBUG` parameter is set to `False` for production!
75122

76-
_to be completed_
123+
## Deployment
77124

78-
* Application ID
79-
* Application Secret
125+
There are many ways to deploy this application. Some options:
80126

81-
### Deployment
127+
### PythonAnywhere
82128

83-
There are many ways to deploy this application. [PythonAnywhere](https://www.pythonanywhere.com/) provides a great place for deploying Flask applications like this. This one could also easily be deployed to AWS Elastic Beanstalk.
129+
[PythonAnywhere](https://www.pythonanywhere.com/) provides a great place for deploying a Flask applications like this. Follow [this](https://help.pythonanywhere.com/pages/Flask/) guide for deployment.
84130

85-
#### Deployment to AWS Elastic Beanstalk
131+
### Deployment to AWS Elastic Beanstalk
86132

87-
Follow [this](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create-deploy-python-flask.html) guide for deployment.
133+
Follow [this](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create-deploy-python-flask.html) guide for deployment to AWS EBS.
88134

89135
As of this writing, AWS Elastic Beanstalk supports Python 3.4.
90136

‎app/__init__.py

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
#----------------------------------------------------------------------------#
2-
# APP CONFIGURATION
3-
#----------------------------------------------------------------------------#
4-
51
# standard library imports
62

73
import os
@@ -15,7 +11,7 @@
1511
import pdb
1612

1713
#----------------------------------------------------------------------------
18-
# APPLICATION CONFIG
14+
# APPLICATION SETUP
1915

2016
app = Flask(__name__)
2117
app.config.from_pyfile('config.py')

‎app/config.example.py

+5-14
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,14 @@
11
# project/_config.py
2-
3-
import os
4-
from datetime import timedelta
5-
6-
# Grabs the folder where the script runs.
7-
basedir = os.path.abspath(os.path.dirname(__file__))
8-
9-
# Enable debug mode.
2+
# Enable debug mode. Be sure to set this to false for production!
103
DEBUG = True
114

12-
# Secret key for session management.
5+
# Secret key for session management. Make sure this is long and very random.
136
SECRET_KEY = ""
147

15-
# Session lifetime (matches lifetime of Esri tokens)
16-
# PERMANENT_SESSION_LIFETIME = timedelta(seconds=3600)
17-
18-
# ESRI IDs for accessing premium AGOL services (elevation and hydrology)
8+
# ESRI IDs for accessing premium AGOL services (elevation and hydrology).
9+
# Get this by registering an application with from developers.arcgis.com.
1910
ESRI_APP_CLIENT_ID = ''
2011
ESRI_APP_CLIENT_SECRET = ''
2112

22-
# MAPBOX Token for better custom basemaps
13+
# MAPBOX Token for custom basemaps. Get this from www.mapbox.com.
2314
MAPBOX_ACCESS_TOKEN = ""

0 commit comments

Comments
 (0)