cookiecutter-dokku-django

A cookiecutter template for creating a Django project with deployment via Dokku (free/libre platform as a service).

Highlights:

• Base well-configured Django with PostgreSQL.
• Efficiently serves Django with gunicorn and whitenoise, optimizing request handling and static file management.
• Simplifies local development with Docker Compose, eliminating virtualenv and Python version conflicts, while mirroring production services.
• Ensures environment consistency with identical Dockerfile, services, settings.py, and HTTP server across local and production.
• Provides sensible defaults, like AutoField over BigAutoField and suppressed DisallowedHost errors.
• Enforces consistent code style with .editorconfig (end-of-line, trailing spaces, indentation).
• Streamlines development with numerous make targets for a standardized workflow.
• Integrates linting with black, isort, autoflake, and flake8.
• Offers optional service integrations:
  • MariaDB as an alternative to PostgreSQL.
  • Celery for background tasks.
  • Redis for task queue and/or cache (considering migrating to Valkey because of licensing issues).
  • Mailhog for local mail testing.
  • MinIO for object storage.
• Includes a step-by-step markdown tutorial for Dokku deployment.

Using

First, install cookiecutter and render the template using your parameters:

pip install cookiecutter
cookiecutter gh:PythonicCafe/cookiecutter-dokku-django
# answer the questions :)
cd <project_slug>
git init .
git add .
git commit -m "First commit"

Then, read the created <project_slug>/README.md for local development instructions and <project_slug/docs/deploy.md> for deployment instructions.

To do

• Fix Dokku healthchecks (do not disable) while having * not in ALLOWED_HOSTS (use httpHeaders from docker-container-healthchecker)
• Add support for using pydokku
• Add a git pre-commit hook to automatically run tests, linter etc.
• Add plenty of possible email backends (SMTP, Sendgrid, Mailgun, AWS SES etc.)
• Add IMAP container for testing (something like antespi/docker-imap-devel or apache/james)
• Configure workflows (CI/CD)
• Enhance .dockerignore
• Pin requirements' versions
• Replace requirements.txt/requirements-development.txt with other dependency file type
• Consolidate linter options in pyproject.toml or setup.cfg to make lint.sh more simple (or just use a couple of commands without options inside Makefile)
• Add option to multistage build when user needs to compile JS/CSS
• Translate docs/deploy.md to other languages (currently only available in Brazilian Portuguese)
• Check things we're missing that other implementations have, like cookiecutter-django, cookiecutter-django-dokku and django-boilerplate

Updating PostgreSQL config file

If you want to change local postgres parameters so you can use less/more memory, workers etc.:

• Run docker run --rm postgres:15-bullseye cat ./usr/share/postgresql/postgresql.conf.sample > "{{ cookiecutter.project_slug }}/docker/conf/db/postgresql.dev.conf"
• Go to pgtune.leopard.in.ua, select your parameters and add to the end of docker/conf/db/postgresql.dev.conf

Note: replace postgres:15-bullseye with the image/version you want to work with.

License options

This repository is licensed under Apache 2.0. When creating your project based on this template you can choose one of the following license options:

• GPL 3
• LGPL 3
• AGPL 3
• Apache 2
• MIT
• BSD
• Closed source

If you decide to use another license, just replace the LICENSE file after rendering the project.