Django Backend Starter Template

A modern, production-ready, batteries-included Django backend template built for rapid application development.

---

🚀 Tech Stack

• Framework: Django 5.0+
• API Engine: Django REST Framework (DRF)
• Admin Interface: Django Unfold (Tailwind-based modern UI)
• Database: PostgreSQL
• Caching & Broker: Redis
• Task Queue: Celery & Celery Beat
• API Documentation: Swagger UI & ReDoc via drf-yasg
• Static Assets: WhiteNoise
• Containerization: Docker & Docker Compose

---

🌟 Key Features

1. Custom User Authentication (apps/account):
   • Email-based authentication (no cumbersome usernames).
   • Profile management with avatar, phone number, and metadata.
   • Built-in LoginHistory and LocationHistory tracking.
   • Standard authentication endpoints (Register, Login, Token Exchange, Password Reset, Profile Update).
   • Clean group and role-based permissions.
2. Modern Admin Panel (utils/admin.py & Django Unfold):
   • Modern Tailwind styling with dark/light mode.
   • Dynamic Dashboard KPI statistics.
   • Responsive sidebar with configurable navigation.
3. Interactive API Documentation (apps/api):
   • Live Swagger UI at /swagger/ and ReDoc at /redoc/.
   • Token authentication banner for test requests.
   • Health check endpoint at /api/v1/health/.
   • Mobile app release versioning (AppVersion).
4. Runtime Dynamic Preferences (dynamic_preferences/):
   • Editable site-wide settings directly from the admin panel (site title, contact email, maintenance mode).
5. Production Ready:
   • Multi-stage Dockerfile and Docker Compose setup.
   • Nginx reverse proxy configuration.
   • Pre-configured Gzip compression, security headers, and media streaming.

---

📁 Project Structure

├── apps/
│   ├── account/              # Custom User, authentication, profile, notifications
│   │   ├── admin/            # Unfold user and group admin
│   │   ├── migrations/       # Initial schema migrations
│   │   ├── models/           # User, LoginHistory, Notification models
│   │   ├── serializers/      # DRF serializers for user & auth
│   │   ├── views/            # Register, login, profile, notification views
│   │   └── urls.py           # Account API endpoints
│   └── api/                  # Core API utilities, versions, health checks
│       ├── admin/            # Version & support admin
│       ├── migrations/       # Initial schema migrations
│       ├── models/           # AppVersion, SupportMessage
│       ├── serializers/      # API serializers
│       ├── views/            # HealthCheck, AppVersion, Swagger views
│       └── urls.py           # Core API routes
├── config/
│   ├── settings/
│   │   ├── base.py           # Base Django settings
│   │   ├── develop.py        # Development settings
│   │   ├── production.py     # Production settings
│   │   └── test.py           # Test settings
│   ├── celery.py             # Celery worker configuration
│   ├── urls.py               # Root URL configuration
│   ├── wsgi.py               # WSGI entry point
│   └── asgi.py               # ASGI entry point
├── dynamic_preferences/       # In-tree runtime preferences registry
├── nginx/
│   └── app.conf              # Nginx reverse proxy config
├── static/                   # Static CSS and JS assets
├── templates/
│   ├── admin/                # Unfold admin dashboard & overrides
│   └── swagger/              # Custom Swagger UI templates
├── utils/                    # Reusable helper modules
│   ├── admin.py              # Unfold AdminSite and dashboard callbacks
│   ├── exceptions.py         # DRF custom exception handler
│   ├── image_compression.py  # Image optimization
│   ├── pagination.py         # Standard REST pagination
│   └── redis.py              # Redis token and cache helpers
├── .env.example              # Environment variables template
├── .env.dev                  # Local development env defaults
├── docker-compose.yml        # Docker compose configuration
├── Dockerfile                # Docker build file
├── manage.py                 # Django CLI
└── requirements.txt          # Python dependencies

---

🛠️ Quick Start

1. Using Docker (Recommended)

1. Clone or copy the template:

   git init my-project
   cd my-project
   

2. Setup environment variables:

   cp .env.example .env.dev
   

3. Build and start services:

   docker compose up -d --build
   

4. Run migrations and create superuser:

   docker compose exec web python manage.py migrate
   docker compose exec web python manage.py createsuperuser
   

5. Access the app:

   • Admin Panel: http://localhost:8000/admin/
   • Swagger Docs: http://localhost:8000/swagger/
   • Health Check: http://localhost:8000/api/v1/health/

---

2. Local Python Environment

1. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your local PostgreSQL and Redis credentials
   

4. Apply migrations:

   python manage.py migrate
   python manage.py createsuperuser
   

5. Run the development server:

   python manage.py runserver
   

---

🔑 Environment Variables Reference

Variable	Description	Default
DJANGO_SECRET_KEY	Unique Django secret key	(Required in production)
DJANGO_DEBUG	Enable debug mode	True
DJANGO_ALLOWED_HOSTS	Comma-separated allowed hostnames	127.0.0.1,localhost
POSTGRES_DB	PostgreSQL database name	app_db
POSTGRES_USER	PostgreSQL user	postgres
POSTGRES_PASSWORD	PostgreSQL password	postgres
POSTGRES_HOST	PostgreSQL host	postgres / localhost
POSTGRES_PORT	PostgreSQL port	5432
REDIS_URL	Redis connection URL	redis://redis:6379/0
SENTRY_DSN	Sentry error tracking DSN	(Optional)

---

📡 API Endpoints Overview

• Auth & Account:
  • POST /api/v1/account/register/ - User registration
  • POST /api/v1/account/login/ - User login & token generation
  • GET /api/v1/account/profile/ - Authenticated user profile
  • PUT /api/v1/account/profile/update/ - Update profile
  • POST /api/v1/account/recover/ - Request password recovery
  • POST /api/v1/account/reset/ - Reset password
• System & Utilities:
  • GET /api/v1/health/ - Server health status
  • GET /api/v1/version/ - Latest mobile application version
  • POST /api/v1/contact-us/ - Submit support/contact message
• Documentation:
  • /swagger/ - Interactive Swagger UI
  • /redoc/ - ReDoc API documentation