nprapps' Project Template
- About this template
- What's in here?
- Copy the template
- Configure the project
- Install requirements
- Project secrets
- Bootstrap issues
- Generate index.html
- Adding a template/view
- Run the project locally
- Compile static assets
- Test the rendered app
- Deploy to S3
- Deploy to EC2
About this template
This template provides a a project skeleton suitable for any project that is to be served entirely as flat files. Facilities are provided for rendering html from data, compiling LESS into CSS, deploying to S3, etc. (It actually supports deploying to servers too, but that's less well-tested.)
What's in here?
The project contains the following folders and important files:
data-- Data files, such as those used to generate HTML.
etc-- Miscellaneous scripts and metadata for project bootstrapping.
less-- LESS files, will be compiled to CSS and concatenated for deployment.
templates-- HTML (Jinja2) templates, to be compiled locally.
www-- Static and compiled assets to be deployed. (a.k.a. "the output")
www/live-data-- "Live" data deployed to S3 via cron jobs or other mechanisms. (Not deployed with the rest of the project.)
app.py-- A Flask app for rendering the project locally.
app_config.py-- Global project configuration for scripts, deployment, etc.
crontab-- Cron jobs to be installed as part of the project.
fabfile.py-- Fabric commands automating setup and deployment.
Copy the template
git clone email@example.com:nprapps/app-template.git $NEW_PROJECT_NAME # Optional: checkout an initial project branch # git checkout [init-map|init-table|init-chat] cd $NEW_PROJECT_NAME rm -rf .git git init git add * .gitignore git commit -am "Initial import from app-template." git remote add origin firstname.lastname@example.org:nprapps/$NEW_PROJECT_NAME.git git push -u origin master
Configure the project
app_config.py and update
REPOSITORY_NAME any other relevant configuration details.
Node.js is required for the static asset pipeline. If you don't already have it, get it like this:
brew install node curl https://npmjs.org/install.sh | sh
Then install the project requirements:
cd $NEW_PROJECT_NAME npm install less universal-jst mkvirtualenv $NEW_PROJECT_NAME pip install -r requirements.txt
Project secrets should never be stored in
app_config.py or anywhere else in the repository. They will be leaked to the client if you do. Instead, always store passwords, keys, etc. in environment variables and document that they are needed here in the README.
The app-template can automatically setup your Github repo with our default labels and tickets by running
fab bootstrap_issues. You will be prompted for your Github username and password.
Adding a template/view
A site can have any number of rendered templates (i.e. pages). Each will need a corresponding view. To create a new one:
- Add a template to the
templatesdirectory. Ensure it extends
- Add a corresponding view function to
app.py. Decorate it with a route to the page name, i.e.
- By convention only views that end with
.htmland do not start with
_will automatically be rendered when you call
Run the project locally
A flask app is used to run the project locally. It will automatically recompile templates and assets on demand.
workon $NEW_PROJECT_NAME python app.py
Visit localhost:8000 in your browser.
With the project running, visit localhost:8000/test/SpecRunner.html.
Compile static assets
workon $NEW_PROJECT_NAME fab render
(This is done automatically whenever you deploy to S3.)
Test the rendered app
If you want to test the app once you've rendered it out, just use the Python webserver:
cd www python -m SimpleHTTPServer
Deploy to S3
fab staging master deploy
Deploy to EC2
The current configuration is for running cron jobs only. Web server configuration is not included.
- Optionally, set
fab staging master setupto configure the server.
fab staging master deployto deploy the app.