Django Project Template

A cookiecutter template for modern Django 6 projects.

What's Included

Core Stack

• Django 6 on Python 3.14 with uv for dependency management
• Custom User model with email-based authentication (no usernames)
• Abstract BaseModel with created_at/updated_at timestamps
• HTMX for interactivity with Tailwind CSS v4 + DaisyUI for styling (no Node.js required, via django-tailwind-cli)

Authentication & Email

• django-allauth for email/password authentication
• SMTP email configuration via environment variables (console fallback for development)
• Async email via send_mail_async background task

Infrastructure

• django-dbtasks as database backend for Django 6's built-in background tasks framework
• django-environ for configuration via environment variables (SQLite default, PostgreSQL via DATABASE_URL)
• SQLite optimizations — WAL mode, synchronous=NORMAL, memory-mapped I/O when using SQLite
• DatabaseCache backend out of the box
• whitenoise for static file serving with brotli compression
• S3 storage support via django-storages (optional, for media files)
• django-health-check for health check endpoints

Monitoring & Security

• sentry-sdk for error tracking (conditional on SENTRY_DSN)
• Production security — HSTS, secure cookies, SSL redirect when DEBUG=False

Development

• pytest with pytest-django and pytest-cov for testing
• ruff for linting and formatting
• pre-commit hooks with ruff and file hygiene checks
• django-debug-toolbar and django-browser-reload (dev-only dependencies)
• bumpver with CalVer versioning (YYYY.0M.0D-INC0)
• justfile with common development commands

Deployment

• Multi-stage Dockerfile with gunicorn and entrypoint script (auto-runs migrate + createcachetable)
• DevContainer configuration for VS Code
• Forgejo Actions for CI/CD (tests, Docker builds, Renovate)
• Renovate for automated dependency updates

Extras

• CLAUDE.md and Playwright MCP config for AI-assisted development
• i18n ready with locale directory and LocaleMiddleware
• Version and environment context processor for templates

Usage

# Install cookiecutter (if you don't have it)
uv tool install cookiecutter

# Generate a new project
cookiecutter https://git.tbrnt.ch/tobru/cookiecutter-django.git

You'll be prompted for:

Variable	Default	Description
project_name	My Project	Human-readable project name
project_slug	my_project	Python-safe slug (auto-derived)
author_name	Your Name	Author or organization
description	A modern Django project	One-line description
domain_name	example.com	Production domain

Getting Started with a Generated Project

cd <project_slug>
just install           # Install dependencies
just migrate           # Run initial migrations
just createsuperuser   # Create admin account
just run               # Start dev server with Tailwind watcher

Run just to see all available commands.

Generated Project Structure

<project_slug>/
  .devcontainer/          DevContainer config
  .forgejo/workflows/     CI/CD workflows
  apps/
    core/                 BaseModel, context processors, async email task
    users/                Custom User model (email-based auth)
  config/                 Django settings, URLs, WSGI
  tests/                  pytest test suite with conftest fixtures
  locale/                 i18n translation files
  static/css/             Tailwind CSS input
  templates/              Base template and allauth overrides
  .env.example            Environment variable reference
  .pre-commit-config.yaml Pre-commit hooks (ruff, file hygiene)
  CLAUDE.md               AI development reference
  Dockerfile              Multi-stage production build
  docker-entrypoint.sh    Startup script (migrate, cache table, gunicorn)
  justfile                Development commands
  manage.py
  pyproject.toml          Dependencies, ruff, pytest, bumpver config

Environment Variables

All configuration is via environment variables. See .env.example in the generated project for the full reference.

Variable	Default	Description
SECRET_KEY	change-me-in-production	Django secret key
DEBUG	False	Debug mode
ALLOWED_HOSTS	(empty)	Comma-separated allowed hosts
ENVIRONMENT_NAME	(empty)	Shown in templates (e.g. "DEV", "STAGING")
DATABASE_URL	SQLite	Database connection URL
EMAIL_HOST	(unset)	SMTP host — when set, enables SMTP backend
SENTRY_DSN	(unset)	Sentry DSN — when set, enables error tracking
AWS_STORAGE_BUCKET_NAME	(unset)	S3 bucket — when set, enables S3 media storage
SECURE_SSL_REDIRECT	True	SSL redirect (only applies when DEBUG=False)

Required Secrets for Forgejo Actions

Secret	Used by
REGISTRY_USERNAME	Docker registry login
REGISTRY_TOKEN	Docker registry login
RENOVATE_TOKEN	Renovate bot access to Forgejo
RENOVATE_GITHUB_TOKEN	Renovate access to GitHub-hosted dependencies