● Python Backend

django-production

Use when auditing Django codebases for production readiness or implementing production best practices with modern tooling (uv, ruff, pytest, Docker, drf-spectacular). Provides automated detection, gap analysis, and step-by-step implementation with ready-to-use configuration templates.

View raw .md →skills.sh →833 lines

Django Production Readiness Skill

Overview

This skill transforms Django projects into production-ready applications with automated quality gates, security scanning, and fast developer feedback loops. It enables "vibe coding" with AI assistants while maintaining production quality through automation.

Core Principles:

Fast feedback - All checks run locally in <30 seconds
Automated gates - Catch issues before code review/CI
Zero manual quality checks - Everything is automated
Modern tooling - uv, ruff, pytest, Docker, drf-spectacular
Production confidence - Ship fast without breaking things

When to Use This Skill

Invoke this skill when you encounter these situations:

Symptoms of needing production readiness:

No pre-commit hooks or linting configured
Using outdated tools (pip+requirements.txt, flake8, black separately)
No automated testing or coverage tracking
Secrets/credentials potentially in version control
No Docker configuration or inconsistent local dev environments
API documentation missing or outdated
No CI/CD pipeline or manual deployment process
Unclear how to validate changes locally before pushing

Proactive use cases:

Starting a new Django project (set up correctly from day 1)
Inheriting an existing Django codebase (audit current state)
Preparing for production deployment (ensure all gates in place)
Migrating from Django REST Framework to modern API practices
Onboarding new developers (standardize local setup)

Pre-Flight Check

Before implementing changes, run these detection commands to audit the current state:

# Check Python package management
ls pyproject.toml 2>/dev/null && echo "✓ pyproject.toml exists" || echo "✗ No pyproject.toml"
command -v uv >/dev/null && echo "✓ uv installed" || echo "✗ uv not installed"

# Check code quality tools
grep -q "ruff" pyproject.toml 2>/dev/null && echo "✓ ruff configured" || echo "✗ ruff not configured"
grep -q "mypy" pyproject.toml 2>/dev/null && echo "✓ mypy configured" || echo "✗ mypy not configured"
ls .pre-commit-config.yaml 2>/dev/null && echo "✓ pre-commit configured" || echo "✗ pre-commit not configured"

# Check testing
grep -q "pytest" pyproject.toml 2>/dev/null && echo "✓ pytest configured" || echo "✗ pytest not configured"
grep -q "pytest-django" pyproject.toml 2>/dev/null && echo "✓ pytest-django configured" || echo "✗ pytest-django not configured"
grep -q "pytest-cov" pyproject.toml 2>/dev/null && echo "✓ coverage configured" || echo "✗ coverage not configured"

# Check security
command -v gitleaks >/dev/null && echo "✓ gitleaks installed" || echo "✗ gitleaks not installed"
ls gitleaks.toml 2>/dev/null && echo "✓ gitleaks configured" || echo "✗ gitleaks not configured"
grep -q "django-environ\|python-decouple" requirements.txt pyproject.toml 2>/dev/null && echo "✓ env vars tool configured" || echo "✗ env vars tool not configured"

# Check Docker
ls Dockerfile 2>/dev/null && echo "✓ Dockerfile exists" || echo "✗ No Dockerfile"
ls docker-compose.yml 2>/dev/null && echo "✓ docker-compose exists" || echo "✗ No docker-compose.yml"

# Check API documentation (if DRF)
python -c "import rest_framework" 2>/dev/null && echo "✓ DRF installed" || echo "✗ DRF not installed"
grep -q "drf-spectacular" requirements.txt pyproject.toml 2>/dev/null && echo "✓ drf-spectacular configured" || echo "✗ drf-spectacular not configured"

# Check CI/CD
ls .github/workflows/*.yml 2>/dev/null && echo "✓ GitHub Actions configured" || echo "✗ No CI configured"

# Check Makefile
ls Makefile 2>/dev/null && echo "✓ Makefile exists" || echo "✗ No Makefile"

Action: Run this pre-flight check and create TodoWrite items for each ✗ (missing) item.

Audit Checklist

Use TodoWrite to create tasks for each category below. Mark as in_progress when auditing, completed when verified.

1. Package Management

Using uv (not pip/poetry/pipenv)
pyproject.toml exists with proper dependencies
uv.lock file present and up-to-date
Dev dependencies separated from production

2. Code Quality Tools

ruff configured (replaces black, flake8, pylint, isort)
mypy or pyright for type checking
Pre-commit hooks installed and running
.ruff.toml or [tool.ruff] in pyproject.toml

3. Testing Infrastructure

pytest + pytest-django configured
pytest-cov for coverage tracking
Coverage target ≥80% defined
factory_boy or model_bakery for test fixtures
Fixtures in conftest.py

4. Security

gitleaks configured and running in pre-commit
django-environ or python-decouple for env vars
.env.example file exists
No secrets in version control
DEBUG=False in production settings
SECRET_KEY from environment variable
ALLOWED_HOSTS properly configured
Security middleware enabled (HSTS, CSP, etc.)

5. Django Configuration

Settings split (base.py, dev.py, prod.py)
Database connection from env vars
Static files configured (STATIC_ROOT, MEDIA_ROOT)
CORS configured if needed (django-cors-headers)
Session/cache backends configured

6. API Documentation (if DRF)

drf-spectacular installed (not drf-yasg)
Spectacular settings configured
OpenAPI schema endpoint configured
Swagger UI accessible at /api/schema/swagger/
ReDoc accessible at /api/schema/redoc/

7. Docker Configuration

Dockerfile exists with multi-stage build
docker-compose.yml for local development
.dockerignore file present
Non-root user configured in container
Health check endpoint configured

8. CI/CD

GitHub Actions workflow exists
Runs linting (ruff)
Runs tests with coverage reporting
Runs security scans (gitleaks, safety)
Builds Docker image on main branch

9. Monitoring & Logging

Sentry SDK installed and configured
Structured logging (JSON format)
Health check endpoint exists
Performance monitoring configured

10. Makefile

Makefile exists with common commands
Fast validation loop (make check)
Easy setup (make install, make dev)

Implementation Phases (Priority Order)

Implement in this order for maximum impact with minimal effort.

Phase 1: Package Management & Dev Environment (CRITICAL)

Why first: Everything else depends on proper dependency management.

Steps:

Install uv (if not present):

curl -LsSf https://astral.sh/uv/install.sh | sh

Create pyproject.toml (or migrate from requirements.txt):
- See template at ~/.claude/skills/django-production/templates/pyproject.toml
- Copy template and adjust project name, Python version, dependencies

Initialize project:

uv sync
source .venv/bin/activate  # or: . .venv/bin/activate

Validation:

uv sync  # Should complete without errors
uv run python --version  # Should show Python 3.11+

Phase 2: Code Quality Tools (HIGH PRIORITY)

Why early: Enables fast feedback loop for AI-first development.

Steps:

Configure ruff in pyproject.toml:
- See template at ~/.claude/skills/django-production/templates/pyproject.toml
- Ruff replaces: black, flake8, pylint, isort, pyupgrade
Set up mypy for type checking:
- Add [tool.mypy] section to pyproject.toml
- Install django-stubs: uv add --dev django-stubs mypy
Create .pre-commit-config.yaml:
- See template at ~/.claude/skills/django-production/templates/.pre-commit-config.yaml
- Install hooks: uv run pre-commit install

Validation:

uv run ruff check .  # Should run linting
uv run ruff format .  # Should format code
uv run mypy .  # Should run type checking
git commit --allow-empty -m "test"  # Pre-commit hooks should run

Phase 3: Testing Infrastructure (HIGH PRIORITY)

Why critical: Core TDD workflow for quality assurance.

Steps:

Install pytest ecosystem:

uv add --dev pytest pytest-django pytest-cov factory-boy

Configure pytest in pyproject.toml:

[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "config.settings.test"
python_files = ["test_*.py", "*_test.py"]
addopts = "--cov --cov-report=html --cov-report=term-missing"

Create conftest.py with common fixtures:

import pytest
from django.contrib.auth import get_user_model

User = get_user_model()

@pytest.fixture
def user(db):
    return User.objects.create_user(
        email="test@example.com",
        password="testpass123"
    )

Set up coverage configuration:

[tool.coverage.run]
source = ["."]
omit = ["*/migrations/*", "*/tests/*", "*/venv/*", "*/.venv/*"]

[tool.coverage.report]
fail_under = 80
show_missing = true

Validation:

uv run pytest  # Should run tests
uv run pytest --cov  # Should show coverage report

Phase 4: Security Foundations (HIGH PRIORITY)

Why critical: Prevent credential leaks and security vulnerabilities.

Steps:

Install gitleaks:

brew install gitleaks  # macOS
# or download from: https://github.com/gitleaks/gitleaks/releases

Create gitleaks.toml:
- See template at ~/.claude/skills/django-production/templates/gitleaks.toml
Add gitleaks to pre-commit hooks:
- Already included in .pre-commit-config.yaml template
Set up environment variable management:
```
uv add django-environ
```
Create .env.example:
- See template at ~/.claude/skills/django-production/templates/.env.example
- Copy to .env and fill in actual values
- Add .env to .gitignore

Update Django settings to use env vars:

import environ

env = environ.Env()
environ.Env.read_env()  # Read .env file

SECRET_KEY = env("SECRET_KEY")
DEBUG = env.bool("DEBUG", default=False)
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=[])

Validation:

gitleaks detect --source . --verbose  # Should find no secrets
uv run python manage.py check --deploy  # Should pass security checks

Phase 5: Django Production Settings (HIGH PRIORITY)

Why required: Production deployment depends on proper settings structure.

Steps:

Split settings into modules:

config/
└── settings/
    ├── __init__.py
    ├── base.py       # Shared settings
    ├── dev.py        # Development overrides
    └── prod.py       # Production overrides

Copy templates:
- ~/.claude/skills/django-production/templates/settings/base.py
- ~/.claude/skills/django-production/templates/settings/dev.py
- ~/.claude/skills/django-production/templates/settings/prod.py
Update environment-specific settings:
- Database connection pooling
- Static files (whitenoise or cloud storage)
- Security headers (HSTS, CSP, X-Frame-Options)
- Session/cache backends

Validation:

DJANGO_SETTINGS_MODULE=config.settings.prod uv run python manage.py check --deploy
# Should pass all deployment checks

Phase 6: API Documentation (MEDIUM PRIORITY - if DRF)

Why valuable: Improves developer experience and API discoverability.

Steps:

Install drf-spectacular:
```
uv add drf-spectacular
```

Add to INSTALLED_APPS in settings:

INSTALLED_APPS = [
    # ...
    'drf_spectacular',
]

Configure REST framework to use spectacular:

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

Add spectacular settings:

SPECTACULAR_SETTINGS = {
    'TITLE': 'Your API',
    'DESCRIPTION': 'API description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

Add URL patterns:

from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerView,
    SpectacularRedocView,
)

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/schema/swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

Document API endpoints with decorators:

from drf_spectacular.utils import extend_schema

@extend_schema(
    summary="List all users",
    description="Returns a paginated list of all users",
    responses={200: UserSerializer(many=True)}
)
def list(self, request):
    # ...

Validation:

uv run python manage.py spectacular --file schema.yml  # Generate schema
# Visit: http://localhost:8000/api/schema/swagger/
# Visit: http://localhost:8000/api/schema/redoc/

DRF-Spectacular Flow Diagram:

User Request
    ↓
Django URL Router
    ↓
DRF View/ViewSet ← drf-spectacular auto-inspects
    ↓                - Serializers
    ↓                - Docstrings
    ↓                - Type hints
    ↓                - @extend_schema decorators
    ↓
OpenAPI Schema Generation
    ↓
    ├─→ Swagger UI (/api/schema/swagger/)
    ├─→ ReDoc (/api/schema/redoc/)
    └─→ OpenAPI JSON/YAML (/api/schema/)

Phase 7: Docker Configuration (MEDIUM PRIORITY)

Why important: Ensures consistent environments and production readiness.

Steps:

Create multi-stage Dockerfile:
- See template at ~/.claude/skills/django-production/templates/Dockerfile
- Uses uv for fast dependency installation
- Non-root user for security
- Multi-stage build for smaller images
Create docker-compose.yml for local dev:
- See template at ~/.claude/skills/django-production/templates/docker-compose.yml
- Includes Django app, PostgreSQL, Redis

Create .dockerignore:

.git
.venv
__pycache__
*.pyc
*.pyo
*.pyd
.Python
env
.env
.coverage
htmlcov

Add health check endpoint to Django:

# urls.py
from django.http import JsonResponse

def health_check(request):
    return JsonResponse({"status": "healthy"})

urlpatterns = [
    path('health/', health_check),
    # ...
]

Validation:

docker build -t myapp:latest .  # Should build successfully
docker run --rm myapp:latest python manage.py check  # Should pass
docker-compose up -d  # Should start all services
docker-compose ps  # All services should be healthy

Phase 8: CI/CD Pipeline (MEDIUM PRIORITY)

Why important: Automates validation and catches issues before deployment.

Steps:

Create .github/workflows/ci.yml:
- See template at ~/.claude/skills/django-production/templates/github-actions-ci.yml
- Runs linting, type checking, tests, security scans
- Builds Docker image
- Reports coverage
Configure secrets in GitHub:
- DOCKER_USERNAME and DOCKER_PASSWORD (if pushing images)
- Any other deployment credentials

Validation:

# Push to GitHub and verify:
# 1. CI workflow runs automatically
# 2. All jobs pass (lint, test, security, build)
# 3. Coverage report uploaded
# 4. Docker image builds successfully

Phase 9: Monitoring & Observability (LOW PRIORITY - post-deployment)

Why later: Important for production operations, but not blocking initial deployment.

Steps:

Install Sentry SDK:
```
uv add sentry-sdk
```

Configure Sentry in settings:

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
    dsn=env("SENTRY_DSN"),
    integrations=[DjangoIntegration()],
    traces_sample_rate=1.0,
    send_default_pii=True,
)

Set up structured logging:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'json': {
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s',
            'class': 'pythonjsonlogger.jsonlogger.JsonFormatter',
        },
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'json',
        },
    },
    'root': {
        'level': 'INFO',
        'handlers': ['console'],
    },
}

Create monitoring endpoints:
- Health check: /health/
- Readiness check: /ready/
- Metrics: /metrics/ (if using Prometheus)

Validation:

# Trigger test Sentry error
uv run python -c "import sentry_sdk; sentry_sdk.init(); 1/0"
# Check Sentry dashboard for event

Makefile - Fast Local Validation

Create a Makefile with these commands for instant feedback:

See full template at: ~/.claude/skills/django-production/templates/Makefile

Essential commands:

.PHONY: install dev test lint format typecheck security-scan check

install:  ## Install all dependencies
	uv sync

dev:  ## Run development server
	uv run python manage.py runserver

test:  ## Run tests
	uv run pytest

lint:  ## Lint code
	uv run ruff check .

format:  ## Format code
	uv run ruff format .

typecheck:  ## Type check
	uv run mypy .

security-scan:  ## Run security scans
	gitleaks detect --source . --verbose
	uv run safety check

check: format lint typecheck test security-scan  ## Run all checks
	@echo "✅ All checks passed!"

Usage:

make install  # Setup project
make dev      # Start development
make check    # Validate before commit (< 30 seconds)

Verification & Validation

After implementing all phases, verify the setup:

Local Verification

# 1. Install and setup
make install

# 2. Run all checks
make check
# Should pass: formatting, linting, type checking, tests, security

# 3. Test pre-commit hooks
git commit --allow-empty -m "test"
# Should run: ruff, mypy, gitleaks, pytest

# 4. Test Docker build
docker build -t myapp:latest .
# Should build successfully

# 5. Check Django deployment settings
DJANGO_SETTINGS_MODULE=config.settings.prod make check
# Should pass all deployment checks

# 6. Verify API docs (if DRF)
make dev
# Visit: http://localhost:8000/api/schema/swagger/
# Should load Swagger UI with all endpoints

CI/CD Verification

# Push to GitHub
git push

# Verify in GitHub Actions:
# ✓ Lint job passes
# ✓ Test job passes (with coverage report)
# ✓ Security job passes
# ✓ Build job passes (Docker image)

Production Readiness Checklist

Troubleshooting

Common Issues

Issue: uv not found

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Add to PATH (follow installation instructions)

Issue: Pre-commit hooks not running

# Reinstall hooks
uv run pre-commit install
# Test manually
uv run pre-commit run --all-files

Issue: Tests failing with "No module named 'config'"

# Ensure DJANGO_SETTINGS_MODULE is set correctly
export DJANGO_SETTINGS_MODULE=config.settings.test
# Or add to pyproject.toml [tool.pytest.ini_options]

Issue: Gitleaks finding false positives

# Add to gitleaks.toml [allowlist] section
paths = [
  '''\.env\.example$''',  # Allow .env.example
  '''tests/fixtures/.*'''   # Allow test fixtures
]

Issue: Docker build failing with permission errors

# Ensure non-root user has correct permissions in Dockerfile
RUN chown -R django:django /app
USER django

Issue: DRF-Spectacular not generating schema

# Ensure drf-spectacular is in INSTALLED_APPS
# Ensure REST_FRAMEWORK['DEFAULT_SCHEMA_CLASS'] is set
# Run: python manage.py spectacular --validate

Issue: mypy errors with Django models

# Install django-stubs
uv add --dev django-stubs
# Add to pyproject.toml:
[tool.mypy]
plugins = ["mypy_django_plugin.main"]

[tool.django-stubs]
django_settings_module = "config.settings"

Success Criteria

This skill has succeeded if:

✅ All local checks run in <30 seconds (make check)
✅ Pre-commit hooks catch issues before commit
✅ Tests pass with ≥80% coverage
✅ No secrets in version control
✅ CI/CD provides fast feedback (<5 minutes)
✅ Docker containers build and run successfully
✅ API documentation is auto-generated and accessible
✅ Production deployment is confident and safe
✅ New developers can set up in <5 minutes (make install && make dev)
✅ AI coding assistants can iterate quickly with automated safety

Template Files

All configuration templates are available at:

~/.claude/skills/django-production/templates/

Key templates:

pyproject.toml - Complete uv + ruff + pytest + mypy config
Makefile - Fast local validation commands
Dockerfile - Multi-stage production build
docker-compose.yml - Local development environment
.pre-commit-config.yaml - Pre-commit hooks
.env.example - Environment variables template
gitleaks.toml - Secret scanning configuration
github-actions-ci.yml - CI/CD pipeline
settings/base.py, settings/dev.py, settings/prod.py - Django settings

Next Steps After Implementation

Run make check - Ensure all local validation passes
Commit changes - Pre-commit hooks will validate automatically
Push to GitHub - CI/CD will run full validation
Monitor Sentry - Set up error tracking for production
Document team workflow - Add README with development instructions
Iterate and improve - Adjust coverage targets, add more tests

References

uv: https://github.com/astral-sh/uv
ruff: https://github.com/astral-sh/ruff
pytest: https://docs.pytest.org/
drf-spectacular: https://drf-spectacular.readthedocs.io/
gitleaks: https://github.com/gitleaks/gitleaks
Django security checklist: https://docs.djangoproject.com/en/5.0/howto/deployment/checklist/

● Authored at Benmore Technologies

benmore.tech →

Used daily by the Benmore forward-deployed engineering team. Built on the open Anthropic Skills format — drop the SKILL.md into any agent that supports skills, or paste it into a web LLM as a system prompt.

Install just this skill

# Claude Code
mkdir -p ~/.claude/skills/django-production
curl -fsSL https://www.arkashj.com/skills/django-production/raw \
  -o ~/.claude/skills/django-production/SKILL.md

# Cursor
curl -fsSL https://www.arkashj.com/skills/django-production/raw \
  -o .cursor/rules/django-production.mdc

# Symlink it back to the upstream copy
ln -s ~/.claude/skills/django-production/SKILL.md .cursor/rules/django-production.mdc