Heroku aiohttp Web Template

An opinionated project template for deploying an aiohttp web app to Heroku, designed to encourage the rapid development and deployment of real-time front-end features.

NB: This template currently tracks an out-of-date version of aiohttp. Please tread carefully. Contributions are welcome to bring it up-to-date.

Launch the app

Use this button:

Or alternatively:

$ git clone https://github.com/sseg/heroku-aiohttp-web.git
$ cd heroku-aiohttp-web
$ heroku create
$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-multi.git
$ heroku config:set ROOT_LOG_LEVEL=INFO
$ git push heroku master

Develop locally

Make sure you have:

• a Python 3.5+ virtual environment (venv)
• node version 4.5+ with npm
• the Heroku CLI tools Heroku Toolbelt

Install the project packages:

$ pip install -r dev-requirements.txt
$ pip-sync
$ npm install -g brunch
$ npm install

Then run the project with development asset server:

$ chmod +x ./dev_start.sh `# run this just once`
$ ./dev_start.sh

Or run the app using compiled assets with the Procfile:

$ npm run clean && npm run build:prod
$ heroku local

Local config values are defined in the .env file, and invoked when you start the application using heroku local.

Run the tests

There are no tests yet... but stay tuned!

Application structure

Handlers

aiohttp dispatches requests to handlers which can be either coroutines or functions that accept a Request and return a Response. A base class aiohttp.web.View is also provided to help organize handlers into classes, which provides the convenience of automatically creating an OPTIONS method.

Templates

This app uses jinja2 templates to construct its index view. Template files are kept in the web/templates directory and compiled by the aiohttp_jinja2 renderer. You might prefer mako for templates, or something else—connecting a new renderer to your handlers is easy.

Static files

Javascript and CSS source files are defined in the assets/js and assets/css directories, respectively. These assets are compiled by brunch to the top-level public directory (configuration in brunch-config.js). You might want to add React or Elm compilation which is as simple as installing a new brunch plugin. In development you can run a file watcher with an HTTP + pushstate server to reload your page on file changes (this is started with the dev_start.sh script).

Production asset delivery

In production the assets are compiled once (triggered during Heroku deployment by package.json's postinstall directive). Based on the Python configuration the compiled assets are served through aiohttp (with the piping handled by web.utils.assets.AssetManager).

NB: the aiohttp server is not designed to serve static files, and allowing it to serve production asset traffic will detrimentally affect your application's performance. You will either want to expose this application behind a content delivery proxy (e.g. Cloudflare) or reconfigure it to serve assets from a separate assets server. The brunch asset compiler is configured here to append checksum digests to asset filenames which facilitates cache eviction in these scenarios.

Configuration

This application uses a configuration base file, config/web.yml, which defines defaults and wraps environment variables. New configuration settings should be added to this file and refer to new environment variables. For more information on Heroku app configuration see the devcenter docs.

Contributions

Contributions are welcome! Bugs, feature requests, and unanswered questions can be reported in the Github issue tracker here. Fixes, enhancements, and suggestions are also gratefully accepted in pull requests.