Django template for Docker + Heroku

This is how I set up Django projects to get up and running as quick as possible. In includes a few neat things:

• Development environment with Docker Compose
• Production environment with Heroku
• Static file compilation with Parcel, so you can use modern JS stuff and SCSS
• Static file serving with Whitenoise
• CI with GitHub actions
• VSCode remote container config with linting, Black, refactoring, etc, all set up sensibly
• A custom User model, which Django recommend doing when starting a project
• Gevent workers and DB connection pooling, so you can serve up lots of requests on a Heroku hobby dyno
• Sentry for exception logging

Getting started

To get started (replace myapp with the name of your app):

$ docker run -it --rm -v "$PWD":/usr/src/app -w /usr/src/app django django-admin.py startproject --template https://github.com/bfirsh/django-docker-heroku-template/tarball/master --name .gitignore,.dockerignore,Dockerfile,README.md,app.json,package.json,script/clean,.vscode/settings.json myapp
$ cd myapp
$ chmod +x ./manage.py script/*

This readme file is now in your app's directory. You can delete this top bit and everything that follows is the start of your app's readme.

{{ project_name }}

Development environment

Install Docker, then run:

$ docker-compose up --build

This will boot up everything that your app needs to run.

(Note: the --build argument is not required, but will ensure the Python and JS dependencies are always up-to-date.)

In another console, run these commands to set up the database and set up a user:

$ docker-compose run web ./manage.py migrate
$ docker-compose run web ./manage.py createsuperuser

The local development environment is now running at http://localhost:8000. The admin interface is at http://localhost:8000/admin/, accessible with the user/pass created above.

Tests

To run the test suite:

$ docker-compose run web ./manage.py test

Deployment on Heroku

This app is designed to be deployed on Heroku.

These commands, roughly, will get you set up with an app. Replace {{ project_name }}-production with a name for the app:

$ heroku update beta
$ heroku plugins:install @heroku-cli/plugin-manifest
$ heroku apps:create --manifest --no-remote --stack=container {{ project_name}}-production
$ heroku config:set -a {{ project_name }}-production SECRET_KEY=$(openssl rand -hex 64)

In the Heroku web UI, go to the app, then the "Deploy" tab, then connect it to a GitHub repo. Then, click "Deploy branch" at the bottom to trigger a deploy. ./manage.py migrate will be run on deploy.

On this page, you can also set up automatic deploys if you want. You probably want to check "Wait for CI to pass before deploy".

Static assets

CSS and JS goes in the assets/ directory. These are compiled by esbuild and postcss into {{ project_name }}/static/dist. You can write any modern JS that esbuild supports -- ES6, JSX, etc.

In development, Docker Compose runs a Parcel daemon alongside your Django development server to compile assets live. For production, Parcel is run in Dockerfile to bake the compiled assets into the production artifact.