djboost 🚀

The modern lifecycle CLI for Django projects.

djboost eliminates repetitive Django setup. Instead of manually installing packages, configuring settings, and writing boilerplate, one command gives you a complete project foundation — DRF, JWT, testing, code quality, security defaults, and more. Add or remove features anytime with safe, dependency-aware add/remove commands.

pip install djboost
djboost startproject myproject

Table of Contents

• Getting Started
• What You Get by Default
• Available Features
• Safe Feature Lifecycle
• Creating Apps
• Creating Accounts App
• Project Management
• Response Format
• Running Your Project
• Dependencies
• CLI Reference

🏁 Getting Started

Step 1 — Create a virtual environment

python -m venv env

# Windows
env\Scripts\activate

# Mac / Linux
source env/bin/activate

Step 2 — Install djboost

pip install djboost

Step 3 — Create your project

mkdir myproject && cd myproject
djboost startproject core

Step 4 — Run it

python manage.py migrate
python manage.py runserver

Open http://127.0.0.1:8000/ — you'll see:

{"message": "API Server Running", "status": "ok"}

📦 What You Get by Default

When you run djboost startproject core, you get a complete foundation without installing any optional packages.

Core Features (Always Included)

What startproject Generates

myproject/
├── apps/                        ← Your Django apps go here
│   └── __init__.py
├── common/                      ← Shared utilities
│   ├── __init__.py
│   ├── responses.py             ← success_response(), error_response()
│   ├── pagination.py            ← CustomPagination
│   └── exceptions.py            ← custom_exception_handler
├── core/                        ← Project configuration
│   ├── __init__.py
│   ├── settings.py              ← Production-oriented settings
│   ├── urls.py                  ← Root URL configuration
│   ├── utils.py                 ← Exception handler
│   ├── wsgi.py
│   └── asgi.py
├── static/                      ← Static files
├── media/                       ← Uploaded files
├── .env                         ← Environment variables (auto-generated)
├── .gitignore                   ← Git ignore rules
├── .pre-commit-config.yaml      ← Code quality hooks
├── manage.py                    ← Django management
├── pytest.ini                   ← Test configuration
└── requirements.txt             ← Frozen dependencies (13 packages)

Installed Packages (13 Essential)

🧩 Available Features (17)

djboost manages 17 features with full dependency tracking. See them all with:

djboost features

Core Features

Infrastructure

Database & Caching

API Features

Realtime

CI/CD

Storage

Security

Observability

Feature Dependency Graph

celery-beat  →  celery          (must have celery first)
kubernetes   →  docker          (must have docker first)
scheduler    ✕  celery-beat     (conflict — pick one)
cicd-github  ✕  cicd-gitlab    (conflict — pick one)

🔒 Safe Feature Lifecycle

Every add and remove command goes through a safe engine that makes operations deterministic and reversible.

What the Safe Engine Does

1. Scans project state — detects which features are already enabled
2. Resolves dependencies — installs required features automatically
3. Detects conflicts — blocks incompatible feature combinations
4. Checks reverse dependencies — warns if other features depend on what you're removing
5. Shows a dry-run plan — preview all changes before applying
6. Backs up files — saves originals before modifying
7. Validates — runs Django checks after changes
8. Auto-rollbacks — reverts everything if validation fails

Dry-Run Mode

Preview what a command would do without making any changes:

djboost add celery --dry-run          # Preview adding Celery
djboost remove docker --dry-run       # Preview removing Docker
djboost add redis-cache --dry-run     # Preview adding Redis Cache

Example output:

Add feature: celery DRY RUN

Packages to install:
  + celery>=5.4,<6
  + redis>=5.0,<6

Files to change:
  + core/celery.py (create)
  + core/tasks.py (create)
  ~ core/__init__.py (modify)
  ~ core/settings.py (modify)
  ~ requirements.txt (modify)

Force Mode

Override conflict checks when you know what you're doing:

djboost remove celery --force         # Remove even if celery-beat depends on it
djboost add scheduler --force         # Add even if celery-beat is installed

What Happens on Failure

If Django validation fails after changes, the safe engine automatically:

1. Restores all backed-up files
2. Removes any created files
3. Reverts package installs/uninstalls
4. Prints what was rolled back

📱 Creating Apps

What

Use djboost startapp to scaffold a new Django app with a professional structure.

Why

Django's built-in startapp gives you a flat, minimal structure. djboost creates an API-oriented layout that separates concerns and scales with your project.

How

cd myproject
djboost startapp products

Generated Structure

apps/products/
├── views/              ← View files (one per resource)
│   ├── __init__.py
│   └── products.py     ← List + Detail views
├── serializers/        ← Serializer files (one per resource)
│   ├── __init__.py
│   └── products.py     ← Detail + List serializers
├── service/            ← Business logic layer
│   ├── __init__.py
│   └── helpers.py      ← Helper functions
├── permissions.py      ← Custom permissions
├── tasks.py            ← Celery tasks (auto-detects if installed)
├── models.py           ← Model with UUID, user FK, timestamps
├── admin.py            ← Admin with list_display, filters
├── urls.py             ← URL patterns (list + detail)
├── apps.py             ← App config
└── tests.py            ← Smoke tests (model, URL, API)

After Creating App

python manage.py makemigrations products
python manage.py migrate
python manage.py runserver

🔐 Creating Accounts App

What

djboost startauth generates a complete authentication system with email-based login, OTP verification, password reset, and profile management.

How

djboost startauth

API Endpoints

🔧 Project Management

Commands

djboost doctor                     # Check project health
djboost validate                   # Validate project structure
djboost info                       # Show project info and modules
djboost features                   # List all available features

djboost features

Shows all 17 features and whether each is enabled:

┌──────────┬─────────────────────┬───────────────────────────────────────────┬──────────────┐
│  Status  │ Feature             │ Description                               │ Dependencies │
├──────────┼─────────────────────┼───────────────────────────────────────────┼──────────────┤
│    ✅    │ Celery              │ Background task processing with Redis      │ —            │
│    ○     │ Celery Beat         │ Periodic task scheduler                   │ celery       │
│    ○     │ APScheduler         │ Lightweight in-process job scheduler      │ —            │
│    ○     │ Docker              │ Containerization with Docker Compose      │ —            │
│    ○     │ Kubernetes          │ K8s deployment manifests                  │ docker       │
│    ○     │ PostgreSQL          │ PostgreSQL database backend               │ —            │
│    ○     │ Redis Cache         │ Redis-backed caching and sessions         │ —            │
│    ○     │ API Documentation   │ Swagger UI and ReDoc                      │ —            │
│    ○     │ GraphQL             │ Strawberry GraphQL API                    │ —            │
│    ○     │ Django Channels     │ WebSocket and async protocol support      │ —            │
│    ○     │ GitHub Actions      │ GitHub Actions CI/CD pipeline             │ —            │
│    ○     │ GitLab CI           │ GitLab CI/CD pipeline                     │ —            │
│    ○     │ Cloud Storage       │ S3-compatible file storage                │ —            │
│    ○     │ Security Headers    │ CSP, HSTS, secure cookies                 │ —            │
│    ○     │ Sentry              │ Error tracking and performance monitoring │ —            │
│    ○     │ Structured Logging  │ Structlog with JSON output                │ —            │
│    ○     │ OpenTelemetry       │ Distributed tracing and metrics           │ —            │
└──────────┴─────────────────────┴───────────────────────────────────────────┴──────────────┘

djboost doctor

Checks your project health:

• ✅ Django configuration
• ✅ Database configuration
• ✅ Environment variables
• ✅ Required packages
• ✅ Common package
• ✅ Apps directory
• ⚠️ DEBUG mode
• ⚠️ SECRET_KEY security

djboost validate

Validates project structure integrity:

• ✅ INSTALLED_APPS configuration
• ✅ REST_FRAMEWORK settings
• ✅ Security headers
• ✅ CORS configuration
• ✅ JWT configuration
• ✅ Common package files
• ✅ URL patterns

📊 Response Format

Success Response

{
    "success": true,
    "message": "Data retrieved successfully.",
    "data": [...]
}

Paginated Response

{
    "success": true,
    "message": "Data retrieved successfully.",
    "data": [...],
    "meta": {
        "count": 100,
        "total_pages": 10,
        "current_page": 1,
        "page_size": 10
    }
}

Error Response

{
    "success": false,
    "message": "Invalid email or password.",
    "data": null,
    "errors": {
        "email": ["This field is required."]
    }
}

Usage in Views

from common.responses import success_response, error_response
from common.pagination import CustomPagination
from apps.products.serializers import ProductSerializer

# Success response
def list_products(request):
    products = Product.objects.all()
    return success_response(
        message="Products retrieved",
        data=ProductSerializer(products, many=True).data
    )

# Error response
def create_product(request):
    serializer = ProductSerializer(data=request.data)
    if not serializer.is_valid():
        return error_response(message="Validation failed", errors=serializer.errors)

# Paginated response
def list_products(request):
    paginator = CustomPagination()
    return paginator.paginate_data(
        queryset=Product.objects.all(),
        request=request,
        serializer_class=ProductSerializer,
    )

🏃 Running Your Project

Without Docker

python manage.py migrate
python manage.py runserver

With Docker

docker-compose up --build

With Celery

# Terminal 1 — Django
python manage.py runserver

# Terminal 2 — Celery Worker
celery -A core worker -l info

# Terminal 3 — Celery Beat (optional)
celery -A core beat -l info

With Kubernetes

# Edit k8s/secrets.yaml with real credentials
# Edit k8s/ingress.yaml with your domain
kubectl apply -f k8s/

📋 Dependencies

Essential (installed with startproject)

Optional (add only when needed)

📖 CLI Reference

djboost --version                  Show version
djboost --help                     Show help

# Create
djboost startproject [NAME]       Create new project (default: core)
djboost startapp NAME             Create standard app
djboost startauth               Create full auth system

# Add (all support --dry-run and --force)
djboost add celery                 Add Celery worker
djboost add celery-beat            Add Celery Beat scheduler
djboost add scheduler              Add APScheduler (alternative to Beat)
djboost add docker                 Add Docker configuration
djboost add kubernetes             Add Kubernetes manifests
djboost add postgres               Add PostgreSQL backend
djboost add redis-cache            Add Redis caching
djboost add api-docs [swagger|redoc|both]  Add API documentation
djboost add graphql                Add GraphQL API
djboost add channels               Add Django Channels (WebSocket)
djboost add cicd github|gitlab     Add CI/CD pipeline
djboost add storage                Add S3 cloud storage
djboost add security               Add security headers (CSP, HSTS)
djboost add sentry                 Add Sentry error tracking
djboost add logging                Add structured logging
djboost add monitoring             Add OpenTelemetry tracing

# Remove (all support --dry-run and --force)
djboost remove celery              Remove Celery
djboost remove celery-beat         Remove Celery Beat
djboost remove scheduler           Remove APScheduler
djboost remove docker              Remove Docker
djboost remove kubernetes          Remove Kubernetes
djboost remove postgres            Remove PostgreSQL (revert to SQLite)
djboost remove redis-cache         Remove Redis Cache
djboost remove api-docs            Remove Swagger/ReDoc
djboost remove graphql             Remove GraphQL
djboost remove channels            Remove Channels
djboost remove cicd github|gitlab  Remove CI/CD
djboost remove storage             Remove Cloud Storage
djboost remove security            Remove Security Headers
djboost remove sentry              Remove Sentry
djboost remove logging             Remove Structured Logging
djboost remove monitoring          Remove OpenTelemetry

# Project Management
djboost features                   List all features and their status
djboost doctor                     Check project health
djboost validate                   Validate project structure
djboost info                       Show project info and modules

📋 Requirements

• Python 3.10+ (tested on 3.10, 3.11, 3.12, 3.13, 3.14)
• Virtual environment (djboost will warn you if not activated)

📄 License

MIT — Munjur Alom