Awesome
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.