Copyright 2013 NPR. All rights reserved. No part of these materials may be reproduced, modified, stored in a retrieval system, or retransmitted, in any form or by any means, electronic, mechanical or otherwise, without prior written permission from NPR.
(Want to use this code? Send an email to email@example.com!)
- About this app
- What's in here?
- Copy the app
- Configure the project
- Install requirements
- Project secrets
- Bootstrap issues
- Adding a template/view
- Run the project locally
- Deploy the app
- Deploy Tumblr themes
About this app
This app provides an HTML form for embedding and a mechanism to crowdsource user-submitted content via a Tumblog.
The following things are assumed to be true in this documentation.
- You are running OSX.
- You are using Python 2.7. (Probably the version that came OSX.)
- You have virtualenv and virtualenvwrapper installed and working.
What's in here?
The project contains the following folders and important files:
confs-- Server configuration files for nginx and uwsgi. Edit the templates, don't touch anything in
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.
tests-- Python unit tests.
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.
public_app.py-- A simple Flask dynamic app that provides an endpoint for form POSTs.
Copy the app
git clone firstname.lastname@example.org:nprapps/shelf-life.git cd shelf-life
Configure the project
app_config.py and update
REPOSITORY_NAME any other relevant configuration details.
NPR apps-specific: Update relevant environment variables with API keys, etc., from Dropbox:
You can either source
~/Dropbox/nprapps/tumblr_oauth_keys.txt (variables will only be set for the life of your current shell):
Or you can append its contents to your bash_profile|bashrc|zshrc:
cat ~/Dropbox/nprapps/tumblr_oauth_keys.txt >> ~/.zshrc
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 shelf-life npm install less universal-jst mkvirtualenv shelf-life 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 shelf-life python app.py
app.py is used for the Tumblr form which will be baked out to a flat file.
To run the simple app that will post to Tumblr (via intermediate server for image uploads):
This will run on
Visit localhost:8000 in your browser.
Deploy the app
There are two parts – deploy the form to S3 and the simple app (
public_app.py) to EC2.
fab <ENV> master setupto configure the server (where ENV is either staging or production).
fab <ENV> master deployto deploy the app.
fab <ENV> deploy_confsto render the server conf files (nginx and uwsgi) and then deploy them to the server. This will also restart your app on the server.
Deploy Tumblr themes
The base Tumblr theme is in the
tumblr/theme.html file. There are included templates in
_social.html. There are also two new constants in
PROJECT_SHORTLINK. These should be changed on a per-project basis.
To deploy a Tumblr theme with local URLs, type
fab staging copy_theme and the theme will be copied to your clipboard to paste into Tumblr. Note: This only works on Mac OSX. On Linux or Windows, use
fab staging write_theme and manually copy the theme HTML from
To deploy a Tumblr theme with production URLs, type
fab production copy_theme and the theme will be copied to your clipbaord to paste into Tumblr. Note: This only works on Mac OSX. On Linux or Windows, use
fab production write_theme and manually copy the theme HTML from