This template is packed with features to help you build amazing APIs:
- User Authentication: Secure token-based authentication with
django-rest-knox. - Background Tasks: Asynchronous task processing with
CeleryandRedis. - API Documentation: Automatic OpenAPI 3 schema generation with
drf-spectacular. - Ready-to-use API Collection: Test every endpoint from your terminal with the bundled Noodle collection — no Postman needed.
- Centralized Logging: Structured JSON logging for easy monitoring.
- Custom User Model: Email-based authentication for a modern user experience.
- AI-Assisted Development: Includes
AGENTS.mdand curated AI skills (Django, Celery) to help AI coding agents produce idiomatic code. - And much more! Explore the documentation to discover all the features.
- 🐋 Docker
- 🐳 Docker Compose
- ⚡ uv (for IDE support)
- 🛠️ make (optional, for shortcuts)
- Use GitHub's template feature (recommended) or clone repository
- Copy
.env.exampleto.envand setREDIS_PASSWORDto a unique URL-safe value, for example fromopenssl rand -hex 32. - Start services:
make up(ordocker compose up). The backend applies migrations automatically. - Create superuser:
make superuser(ordocker compose exec backend python manage.py createsuperuser) - Access API at
http://localhost:8000
Quick Commands:
make help # See all available commands
make test # Run tests
make seed # Populate database with sample data
make logs # View application logsmake seed is available only with DEBUG=True. Sample users receive random passwords
that are not printed. Create your administrator with make superuser, then set its
credentials in api-collection/.environments/local.env before testing authentication.
The Compose stack is for local development. Source directories mount read-only for live
editing; the host .env and .git are not mounted. All published ports bind to loopback,
and Redis requires REDIS_PASSWORD. make docs-serve opens port 8001 only while serving
documentation. Use make makemigrations for a temporary writable app mount when generating
migrations. All app services build the shared image on startup and have service-specific
health checks. Production requires a WSGI/ASGI server, TLS, explicit ALLOWED_HOSTS,
REDIS_URL, and CELERY_BROKER_URL; use authenticated TLS connections for remote Redis.
API throttles ignore X-Forwarded-For by default. Set NUM_PROXIES only behind proxies
that sanitize that header and prevent direct access. Request logs record the direct peer IP.
Try the API with Noodle:
The repo includes a Noodle collection (api-collection/) covering all v1 endpoints. Install the CLI, start the stack, and run requests:
curl -LsSf https://noodlerest.dev/install.sh | sh # or: brew install noodle
noodle -c api-collection # open interactively
noodle request run core/ping --collection api-collection # or run a single requestSee API Collection (Noodle) for authentication and environment setup.
For IDE support (IntelliSense, autocomplete):
uv sync --all-extrasThis installs dependencies locally so your IDE can provide code completion while your code runs in Docker.
Customize Your Project:
Search for TODO comments across the codebase to find guided setup steps:
pyproject.toml— update project name, version, description, authors, licenseconf/urls.py— change admin URL, delete example index view, disable unused auth endpointsconf/settings.py— adjust throttle rates and DRF Spectacular settings
This documentation is your guide to building amazing applications with the Django Starter Template. Use the navigation on the left to explore the different sections.
- Development: Learn about the development workflow, including how to run tests, and use the scripts.
- Project Structure: Get an overview of the project's directory structure.
- Project Settings: Understand the available settings and how to configure your project.
- Dependencies: See a list of all the project's dependencies.
- Authentication: Learn how to use the authentication and user management endpoints.
- Core App: Discover the core functionalities and API endpoints.
- Logging: Understand the logging system and how to use it.
- Celery Tasks: Learn how to create and manage background tasks.
- Rate Limiting: Configure rate limiting to protect your API.
- Database Seeding: Learn how to seed your database with initial data.
- Testing: Understand how to run and write tests for your project.
- Environment Setup: Learn how to set up your development environment.
- AI-Assisted Development: Learn how the project helps AI coding agents work with your codebase.
