🚒 A recipe for building 12-factor Python / Django web apps with multi-container Docker and deploying to Amazon AWS using Elastic Beanstalk.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



🚒 A recipe for building 12-factor Python / Django web apps with multi-container Docker and deploying to Amazon AWS using Elastic Beanstalk.

No Maintenance Intended

The aim of Dockdj is to provide an example of how to quickly create a Django web application following the Twelve Factor App principals.

The Twelve Factors

  1. Codebase
    One codebase tracked in revision control, many deploys
    βœ… Yup, GitHub
  2. Dependencies
    Explicitly declare and isolate dependencies
    βœ… Yup, uses requirements.txt
  3. Config
    Store config in the environment
    βœ… Yup, uses .env files
  4. Backing Services
    Treat backing services as attached resources
    βœ… BYOBacking service
  5. Build, release, run
    Strictly separate build and run stages
    βœ… gulp, bin/image, bin/stevedore, bin/deploy
  6. Processes
    Execute the app as one or more stateless processes
    βœ… Thanks Docker!
  7. Port binding
    Export services via port binding
    βœ… 80 & 8010
  8. Concurrency
    Scale out via the process model
    βœ… Keep your sessions in Redis or DB
  9. Disposability
    Maximize robustness with fast startup and graceful shutdown
    βœ… Thank Docker!
  10. Dev/Prod parity
    Keep development, staging, and production as similar as possible
    βœ… Yup
  11. Logs
    Treat logs as event streams
    βœ… Yup
  12. Admin Processes
    Run admin/management tasks as one-off processes
    🚫 Does not Apply


This repo contains a simple Python Django 1.8 web app as well as the configuration for both Django and NGINX Docker images. There are also some Bash scripts to help automate the build, release and deploy process.


  • Python 3.4
  • Django 1.8
  • Gunicorn app server
  • Nginx web server
  • Sass css preprocessor
  • Bootstrap 4-alpha CSS framework
  • Gulp build system

Get Started

This document assumes you are running OS X. These are the requirements needed by the bin/install script;

  • Bash
  • XCode & command line utilities
  • Homebrew 0.9+

Additionally these requirements are installed:

These steps will get you running locally:

  1. ./bin/install will provision your local development machine for the first time. It will
  • install all requirements (if they don't exist)
  • creates and starts a Docker virtual machine
  1. Copy environments/dev/.env.example to environments/dev/.env and edit the values. Please make sure to change the following keys:
  • ENV_SECRET_KEY create your own Django secret key
  • ENV_CDN to your Docker host IP: docker-machine ip docker-vm
  • Optionally:
    • ENV_AWS_EB_ENVIRONMENT_NAME to your Amazon AWS Elastic Beanstalk environment name
    • ENV_DOCKER_HUB_REPO_PATH to your Docker repo (Create one if you plan to publish images to Docker Hub.)
  1. Create a dev python environment: pyvenv environments/dev/pyvenv
  2. ./bin/image dev build will create "dev" Docker images with all dependencies installed.
  3. ./bin/stevedore dev start will run the dev Docker containers, open the browser, and tail the logs. At this point you're viewing running source code!
  • ctrl+c stops the logs ./bin/stevedore dev stop will stop the Docker containers.
  • ./bin/stevedore dev logs resumes log tailing.
  1. Optionally, to build frontend assets (CSS, images, etc):
  • Run ./bin/stevedore dev build:dev

You can typically connect to your web application at:

You should now be up and running. Welcome.


Read more about deploying with Amazon AWS Elastic Beanstalk, version numbering, running deployments, hotfix / patch deployments, Docker Hub, and more on the Deployments wiki page.

Testing & Code Quality Tooling

Read more about the set of tools for managing, testing and deploying.