๐ข Django Keel
A versatile, production-ready Django project template for any use case
Build SaaS applications, API backends, web apps, or internal tools with one template.
Note
๐ผ Available for Hire โ Need help with Backend Development or DevOps? I specialize in Django, Python, Kubernetes, CI/CD, and cloud infrastructure. ๐ง Contact: sanyam@sanyamkhurana.com
Django Keel is a comprehensive Copier template that adapts to your needsโwhether youโre building a multi-tenant SaaS with billing, a simple API backend, a traditional web app, or an internal corporate tool. One template, infinite possibilities.
Choose your project type and get smart defaults. Or customize everything yourself.
๐ข What is a โKeelโ?
Inโฆ
๐ข Django Keel
A versatile, production-ready Django project template for any use case
Build SaaS applications, API backends, web apps, or internal tools with one template.
Note
๐ผ Available for Hire โ Need help with Backend Development or DevOps? I specialize in Django, Python, Kubernetes, CI/CD, and cloud infrastructure. ๐ง Contact: sanyam@sanyamkhurana.com
Django Keel is a comprehensive Copier template that adapts to your needsโwhether youโre building a multi-tenant SaaS with billing, a simple API backend, a traditional web app, or an internal corporate tool. One template, infinite possibilities.
Choose your project type and get smart defaults. Or customize everything yourself.
๐ข What is a โKeelโ?
In nautical terms, the keel is the structural backbone of a shipโrunning along the bottom from bow to stern. It provides:
- Stability - Prevents the ship from capsizing in rough waters
- Direction - Keeps the vessel on course, resisting sideways drift
- Foundation - The first part built, upon which the entire ship is constructed
Similarly, Django Keel provides the structural foundation for your Django projects:
- Stability - Production-ready defaults and battle-tested patterns
- Direction - Clear project structure and 12-Factor App compliance
- Foundation - A solid base to build upon, whether youโre sailing smooth seas or navigating stormy deployments
Just as a shipโs keel allows it to sail anywhere, Django Keel enables you to deploy your application to any platformโKubernetes, AWS, Fly.io, Render, or traditional servers.
Table of Contents
- ๐ Feature Availability
- โ๏ธ Default Configuration
- ๐ Security Baseline
- ๐ Template Updates & Versioning
- ๐งช Compatibility & Support
- โจ Features
- ๐ Quick Start
- ๐งช Testing
- ๐ Documentation
- ๐จ Project Types & Examples
- ๐ Updating Your Project
- ๐ค Contributing
- ๐ License
- ๐ Credits
- ๐ Support
๐ Feature Availability
Before diving in, hereโs whatโs included by default, optional, or planned (grouped by category):
Core (Always Included)
| Feature | Status | Notes |
|---|---|---|
| Django 5.2 + Python 3.12/3.13 | โ Included | Always enabled |
| Custom User Model | โ Included | Email-based authentication |
| Split Settings (dev/test/prod) | โ Included | 12-Factor App ready |
| Docker + Compose | โ Included | Local development |
| pytest + coverage | โ Included | Coverage gate configurable (default 80%) |
| ruff + mypy | โ Included | Code quality enforced |
| Health/readiness endpoints | โ Included | /health/ and /ready/ |
API & Frontend
| Feature | Status | Notes |
|---|---|---|
| Django REST Framework | ๐ฆ Optional | Enable with api: drf (or api: both for DRF + GraphQL) |
| Strawberry GraphQL | ๐ฆ Optional | Enable with api: graphql (or api: both for DRF + GraphQL) |
| HTMX + Tailwind CSS | ๐ฆ Optional | Enable with frontend: htmx-tailwind |
| Next.js | ๐ฆ Optional | Enable with frontend: nextjs (requires Node.js 20 LTS+) |
Background Tasks & Async
| Feature | Status | Notes |
|---|---|---|
| Celery (Beat/Flower) | ๐ฆ Optional | Enable with background_tasks: celery (enabled by default) |
| Temporal | ๐ฆ Optional | Enable with background_tasks: temporal |
| Django Channels (WebSockets) | ๐ฆ Optional | Enable with use_channels: true |
Note on Temporal: Requires Temporal Cloud or a self-hosted Temporal cluster. Keel wires the client SDK + example worker with sample workflows/activities; the Temporal server/Cloud is not provisioned.
Observability
| Feature | Status | Notes |
|---|---|---|
| Structured JSON Logging | โ Included | Always enabled |
| Sentry | ๐ฆ Optional | observability: standard or full (enabled by default) |
| OpenTelemetry | ๐ฆ Optional | observability: full only |
| Prometheus metrics | ๐ฆ Optional | observability: full only |
SaaS Features
| Feature | Status | Notes |
|---|---|---|
| Multi-tenant teams (RBAC) | ๐ฆ Optional | Enable with use_teams: true |
| Stripe (basic) | ๐ฆ Optional | Enable with use_stripe: basic |
| Stripe (dj-stripe) | ๐ฆ Optional | Enable with use_stripe: advanced |
| 2FA (TOTP) | ๐ฆ Optional | Enable with use_2fa: true |
Additional Features
| Feature | Status | Notes |
|---|---|---|
| SOPS (encrypted secrets) | ๐ฆ Optional | Enable with use_sops: true |
| PostgreSQL FTS | ๐ฆ Optional | Enable with use_search: postgres-fts |
| OpenSearch | ๐ฆ Optional | Enable with use_search: opensearch |
| i18n/l10n | ๐ฆ Optional | Enable with use_i18n: true |
Deployment Targets
| Feature | Status | Notes |
|---|---|---|
| Kubernetes (Helm + Kustomize) | ๐ฆ Optional | Enable with deployment_targets: [kubernetes] |
| AWS ECS Fargate (Terraform) | ๐ฆ Optional | Enable with deployment_targets: [ecs] |
| Fly.io | ๐ฆ Optional | Enable with deployment_targets: [flyio] |
| Render | ๐ฆ Optional | Enable with deployment_targets: [render] |
| AWS EC2 (Ansible) | ๐ฆ Optional | Enable with deployment_targets: [aws-ec2-ansible] |
Legend:
- โ Included - Always generated, core to every project
- ๐ฆ Optional - Choose during project generation (some enabled by default)
- ๐ฎ Planned - Coming in future releases
Project Type Defaults (What Changes Automatically)
| Type | API | Frontend | Teams | Stripe | Background | Deploy |
|---|---|---|---|---|---|---|
| saas | drf | nextjs | โ on | advanced | celery | kubernetes |
| api | drf | none | โ off | โ off | celery | render |
| web-app | none | htmx-tailwind | โ off | โ off | celery | flyio |
| internal-tool | drf | htmx-tailwind | โ on | โ off | celery | aws-ec2-ansible |
| custom | pick | pick | pick | pick | pick | pick |
โ๏ธ Default Configuration
When you press Enter on every prompt (choosing defaults for project_type: custom):
# Project Type
project_type: custom # Or: saas, api, web-app, internal-tool
# Dependency Management
dependency_manager: uv # Or: poetry
python_version: "3.13" # Or: "3.12"
# Database & Cache
database: postgresql # Production-ready database
db_managed: true # Use managed DB (RDS/Cloud SQL recommended)
cache: redis # Or: none
# API & Frontend
api: drf # Or: graphql, both, none
frontend: none # Or: htmx-tailwind, nextjs
# Authentication
auth: allauth # Or: jwt, both
use_2fa: false # Two-factor authentication disabled
# Background Tasks
background_tasks: celery # Or: temporal, both, none (optional, **enabled by default**)
use_channels: false # WebSockets disabled
# Observability
observability: standard # Or: minimal, full
# minimal = JSON logs + health
# standard = minimal + Sentry
# full = standard + Prometheus + OTel
# SaaS Features
use_teams: false # Multi-tenancy disabled
use_stripe: false # Or: basic, advanced
# Additional Features
use_search: none # Or: postgres-fts, opensearch
use_i18n: false # Internationalization disabled
use_sops: false # Encrypted secrets disabled
# Security
security_profile: standard # Or: strict (see docs for differences)
# Storage
media_storage: aws-s3 # Or: gcs, azure, whitenoise-only
# Deployment
deployment_targets: [kubernetes] # Or: [aws-ec2-ansible, ecs, flyio, render]
# CI/CD
ci_provider: github-actions # Or: gitlab-ci, both
๐ก Tip: Select a project type (saas, api, web-app, internal-tool) for smarter defaults!
Note: Some โoptionalโ features are enabled by default for production-ready projects (e.g., Celery, Sentry via observability: standard). You can disable them during generation.
๐ Security Baseline
Django Keel enforces production security out of the box:
Included Security Features
- โ
python manage.py check --deployruns in CI - โ HSTS (HTTP Strict Transport Security) enabled in production
- โ
Secure cookies (
SECURE_*flags) in production - โ SSL redirect enforced in production
- โ CSP headers (Content Security Policy) with sane defaults
- โ Admin hardening - Custom admin URL, staff-only access
- โ Rate limiting - Optional with django-ratelimit
- โ Brute-force protection - Optional with django-axes
- โ SOPS (age) - Encrypted secrets management (optional)
- โ
.env.example- Template for environment variables - โ No secrets in repo - Environment-based configuration
GitHub Security (when using GitHub Actions)
- OIDC to cloud providers (no long-lived keys)
- Dependabot enabled for dependency updates
- Secret scanning enabled
- Branch protection recommended
security_profile: strict
When you enable security_profile: strict, additional hardening is applied:
- CSP locked to โselfโ - Content Security Policy blocks all external resources
- Admin path randomized - Admin URL is generated randomly (not
/admin/) - Session age shortened - Sessions expire faster (15 min vs 2 weeks)
- HTTPS-only cookies - All cookies require HTTPS, no fallback
- SECURE_HSTS_PRELOAD - Enabled for HSTS preload list submission
- Stricter CORS - No wildcards, explicit origins only
- Additional headers - X-Frame-Options, X-Content-Type-Options, Referrer-Policy
- Permissions-Policy - Restrictive policy (e.g.,
camera=(), geolocation=(), microphone=())
Production Checks
Every generated project includes:
# Security audit
just security-check
# This runs:
# - python manage.py check --deploy
# - pip-audit (dependency vulnerabilities)
# - safety check (known security issues)
๐ Security Policy: We follow Djangoโs security best practices and respond to vulnerabilities within 24 hours. Report issues to security@django-keel (coming soon).
๐ Template Updates & Versioning
How Updates Work
Django Keel uses semantic versioning (SemVer):
- MAJOR (2.0.0) - Breaking changes requiring manual intervention
- MINOR (1.1.0) - New features, backward compatible
- PATCH (1.0.1) - Bug fixes, backward compatible
Your project tracks the template version in .copier-answers.yml:
_commit: a1b2c3d
_src_path: gh:CuriousLearner/django-keel
Updating Your Project
cd your-project
# Create a backup branch before updating
git switch -c pre-update
# Run update
copier update
# If issues arise, you can rollback
git reset --hard
Copier will:
- Show you a diff of changes
- Let you selectively accept/reject changes
- Preserve your customizations
- Handle merge conflicts intelligently
Breaking Changes
We mark breaking changes in the CHANGELOG with a โ ๏ธ BREAKING label and provide migration guides.
Policy: We aim for no more than 2 major versions per year to minimize disruption.
๐งช Compatibility & Support
Tested Combinations
We test Django Keel against:
| Python | Django | Status |
|---|---|---|
| 3.12 | 5.1 | โ Tested |
| 3.12 | 5.2 | โ Tested |
| 3.13 | 5.1 | โ Tested |
| 3.13 | 5.2 | โ Tested |
Support Policy
- Python: Last 2 minor versions (currently 3.12, 3.13)
- Django: Last 2 minor versions (currently 5.1, 5.2)
- LTS versions get priority bug fixes
- Security patches backported for 1 year
CI Testing
Every commit is tested against:
- โ All Python + Django combinations
- โ Template generation with all project types
- โ Docker builds
- โ Code quality (ruff, mypy)
- โ Security checks (pip-audit, safety)
- โ SBOM generation (Syft)
- โ Container image scanning (Trivy)
โจ Features
๐ฏ Core
-
Django 5.2 with Python 3.12/3.13
-
uv or Poetry for blazing-fast dependency management
-
12-Factor App aligned - Implements all 12 factors in practice (docs)
-
Single codebase with multiple deploys
-
Explicit dependencies with lock files
-
Config in environment variables
-
Backing services as attached resources
-
Separate build/release/run stages (
Procfile,release.sh) -
Stateless processes
-
Port binding export
-
Horizontal scalability via process model
-
Fast startup, graceful shutdown
-
Dev/prod parity
-
Logs as event streams
-
Admin processes as one-off tasks
-
Custom User Model from day one
-
Split Settings (base/dev/test/prod)
-
Docker + Compose for local development - Postgres, Redis, and Mailpit included out-of-the-box
๐ Authentication & Security
- django-allauth with email verification
- JWT authentication (SimpleJWT)
- 2FA support (TOTP)
- Security hardening (HSTS, CSP, etc.)
- SOPS for encrypted secrets
- Rate limiting and brute-force protection
๐ API Options
- Django REST Framework with drf-spectacular (OpenAPI 3.0)
- Strawberry GraphQL (modern, type-safe)
- CORS configuration
- API versioning ready
- Automatic schema generation
๐จ Frontend Options
- None (API-only)
- HTMX + Tailwind CSS (modern, minimal JS) - Alpine.js available as optional addition
- Next.js (full-stack React)
โก Async & Background Tasks
- Celery - Traditional async tasks (emails, reports, high-volume processing)
- Temporal - Durable workflows (onboarding, payment flows, long-running processes)
- Both - Use Celery AND Temporal together
- Celery Beat for periodic tasks
- Flower for monitoring
- Django Channels for WebSockets (optional)
๐ Observability
- Structured JSON Logging (always included)
- Sentry error tracking (optional)
- OpenTelemetry distributed tracing (optional,
observability: full) - Prometheus metrics (optional,
observability: full) - Health and readiness endpoints (always included)
Note: OpenTelemetry and Prometheus add overhead and cost. Enable only when needed and configure exporters appropriately.
๐ Deployment
-
Kubernetes (Enterprise-scale):
-
Helm charts
-
Kustomize overlays (dev/staging/prod)
-
PostgreSQL options: Managed (RDS recommended) or CloudNativePG operator
-
Traefik + cert-manager for ingress
-
Horizontal Pod Autoscaling
-
ArgoCD ready
๐ก K8s DB Guidance: Start with managed Postgres (RDS/Cloud SQL/Azure Database) unless you have strong operational reasons for CloudNativePG. Both paths included.
AWS ECS Fargate (Serverless containers):
- No EC2 instance management
- Application Load Balancer with auto-scaling
- Multi-AZ high availability
- Terraform infrastructure-as-code
Fly.io (Global edge):
- Deploy close to users worldwide
- Automatic HTTPS & SSL
- PostgreSQL & Redis included
- Free tier available
- Multi-region deployment
Render (Platform-as-a-Service, PaaS):
- One-click deployment from GitHub
- Auto-deploy on git push
- PostgreSQL & Redis included
- Free and paid tiers
- Zero configuration
AWS EC2 (Ansible) (Full control):
- Ubuntu 24.04 playbooks
- Caddy reverse proxy with auto-HTTPS
- Systemd services
- Zero-downtime deploys (socket activation/rolling restart)
Docker (Universal):
- Multi-stage optimized builds
- docker-compose for development
- Deploy anywhere
๐งช Developer Experience
-
ruff for linting and formatting (10-100x faster)
-
Comprehensive rule set (13+ categories)
-
100-character line length
-
Modern Python 3.12+ type hints
-
mypy + django-stubs for type checking
-
pytest with coverage reporting (coverage gate configurable, default 80%)
-
pre-commit hooks for automated quality checks
-
Just task runner with essential commands:
just dev # Start development server
just test # Run test suite
just lint # Lint and format code
just migrate # Run migrations
just createsuperuser # Create admin user
A focused set of commands (extendable) for all common workflows.
- Docker Compose for local development
- VS Code Devcontainer support
- MkDocs Material documentation
- Infrastructure validation (YAML, Docker Compose, Helm, Ansible)
๐ผ SaaS Features (Optional)
-
Multi-tenant teams (RBAC) - Full team management system
-
Owner/Admin/Member roles
-
Team invitations with email tokens
-
Per-seat billing integration
-
Advanced Stripe Integration - Production-ready billing
-
Basic mode (stripe API) or Advanced mode (dj-stripe)
-
Subscription management with metadata
-
Per-seat and usage-based billing
-
Webhook handlers for all events
-
Customer portal integration
-
Feature Gating - Subscription-based access control
-
@subscription_required,@feature_required,@plan_requireddecorators -
Usage limit checking
-
Class-based view mixins
-
User Impersonation - Admin support tools
-
Staff can impersonate users for debugging
-
Full audit logging
-
Security checks built-in
-
Feature Flags - A/B testing with django-waffle
-
Flags, switches, and samples
-
User/group-based targeting
-
Gradual rollouts
๐ฆ Additional Features
- PostgreSQL Full-Text Search or OpenSearch
- Internationalization (i18n/l10n)
- Professional email template system
๐ Template Updates
- Built-in Copier update mechanism
- Track template version
- Merge upstream changes easily
๐ Quick Start
Prerequisites
- Python 3.12+
- Copier (
pipx install copier) - Docker & Docker Compose
Next.js option? Install Node.js 20 LTS (or later) and pnpm/npm/yarn.
Create a New Project
# Using copier
copier copy gh:CuriousLearner/django-keel your-project-name
# Follow the interactive prompts
What Gets Generated
your-project/
โโโ apps/ # Django applications
โ โโโ core/ # Core functionality (health checks, etc.)
โ โโโ users/ # Custom user model
โ โโโ api/ # API endpoints (if selected)
โโโ config/ # Django configuration
โ โโโ settings/ # Split settings
โ โโโ urls.py
โ โโโ wsgi.py
โ โโโ asgi.py
โโโ deploy/ # Deployment configs
โ โโโ k8s/ # Kubernetes (Helm + Kustomize)
โ โโโ ecs/ # AWS ECS Fargate (Terraform)
โ โโโ flyio/ # Fly.io configuration
โ โโโ render/ # Render blueprints
โ โโโ ansible/ # EC2/Ansible playbooks
โโโ fly.toml # Fly.io config (if selected)
โโโ render.yaml # Render blueprint (if selected)
โโโ docs/ # MkDocs documentation
โโโ tests/ # Test suite
โโโ Dockerfile # Production image
โโโ docker-compose.yml # Development environment
โโโ Justfile # Task runner
โโโ pyproject.toml # Dependencies & config
โโโ README.md
Start Developing
cd your-project
# Install dependencies (uv)
uv sync
# Start services
docker compose up -d
# Run migrations
just migrate
# Create superuser
just createsuperuser
# Start development server
just dev
Visit:
- Application: http://localhost:8000
- Admin: http://localhost:8000/admin/
- API Docs: http://localhost:8000/api/schema/swagger/ (only when
api != none) - Mailpit: http://localhost:8025 (email testing)
๐งช Testing
The template includes comprehensive test suites for both the template itself and generated projects.
Template Tests
# Run all template tests
pytest
# Run with coverage
pytest --cov
# Comprehensive test suite covering:
# - Django integration and compatibility
# - Feature generation for all project types
# - Project structure validation
# - Conditional file generation based on selections
Generated Project Tests
Each generated project includes a complete test suite with conditional test files:
cd your-project
just test
# Tests include:
# - Core functionality (health checks, settings, middleware)
# - User authentication and permissions
# - API endpoints (when enabled)
# - Celery tasks (when enabled)
# - Stripe integration (when enabled)
# - WebSocket functionality (when enabled)
# - 2FA authentication (when enabled)
๐ Documentation
Full documentation: https://django-keel.readthedocs.io/
Template Documentation
- Quick Start - Get started in 5 minutes
- Installation Guide - Detailed setup instructions
- Features Overview - All available features
- API Options - DRF, GraphQL, or both
- Deployment Guides - Kubernetes, AWS EC2, Docker
- Contributing - How to contribute
Generated Project Documentation
Each generated project includes its own comprehensive documentation in the docs/ directory:
- Getting Started & Installation
- Configuration
- API Development
- Testing Guide
- Deployment (Kubernetes, EC2)
- Architecture Overview
- Monitoring & Observability
๐จ Project Types & Examples
Django Keel adapts to your project needs with smart defaults based on project type:
๐ SaaS Application
Perfect for: Multi-tenant SaaS products with billing
project_type: saas
# Smart defaults:
# - API: DRF for backend
# - Frontend: Next.js for modern SPA
# - Teams: Enabled (multi-tenancy)
# - Stripe: Advanced mode with dj-stripe
# - Background: Celery for emails/async tasks
# - Deployment: Kubernetes for scale
๐ API Backend
Perfect for: Mobile apps, microservices, headless backends
project_type: api
# Smart defaults:
# - API: DRF only
# - Frontend: None
# - Teams: Disabled
# - Stripe: Disabled
# - Background: Celery for async processing
# - Deployment: Render for easy hosting
๐ Web Application
Perfect for: Traditional Django web apps, MVPs, content sites
project_type: web-app
# Smart defaults:
# - API: None (traditional Django views)
# - Frontend: HTMX + Tailwind CSS
# - Teams: Disabled
# - Stripe: Disabled
# - Background: Celery for emails
# - Deployment: Fly.io for global edge
๐ข Internal Tool
Perfect for: Corporate dashboards, admin panels, internal systems
project_type: internal-tool
# Smart defaults:
# - API: DRF for flexibility
# - Frontend: HTMX + Tailwind CSS
# - Teams: Enabled (departments/groups)
# - Stripe: Disabled (no billing)
# - Background: Celery for reports
# - Deployment: AWS EC2 (on-premise friendly)
โ๏ธ Custom Configuration
Perfect for: Unique requirements, maximum control
project_type: custom
# You choose everything yourself!
# All options will be presented with sensible defaults
๐ Real-World Examples
Startup SaaS:
project_type: saas
use_stripe: advanced # Combines use_stripe + stripe_mode
use_teams: true
frontend: nextjs
deployment_targets: [kubernetes]
Mobile App Backend:
project_type: api
auth: jwt
use_channels: true # WebSockets for real-time features
deployment_targets: [render]
Company Blog:
project_type: web-app
frontend: htmx-tailwind
use_search: postgres-fts
deployment_targets: [flyio]
Enterprise Dashboard:
project_type: internal-tool
use_teams: true # Departments/groups
security_profile: strict
deployment_targets: [aws-ec2-ansible]
๐ Updating Your Project
When the template is updated, you can pull in changes:
cd your-project
copier update
Copier will intelligently merge changes, respecting your modifications.
๐ค Contributing
Contributions are welcome! Please see CONTRIBUTING.md for details.
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Credits
Django Keel is inspired by:
- django-init - 10+ years of Django best practices
- scaf - Copier-based approach and K8s patterns
- cookiecutter-django - Production-ready defaults
- wemake-django-template - Code quality focus
๐ Star History
If you find Django Keel useful, please consider starring the repository!
๐ Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Docs: Generated in your projectโs
docs/directory
Built with โค๏ธ by the Django community