djinit/README.md

djinit

PyPI did not allow the original name, so the package is released as djinitx

A fast, interactive CLI to bootstrap a modern, production‑ready Django project in minutes — featuring split settings, DRF and JWT integration, OpenAPI docs, CORS, static file handling via WhiteNoise, Postgres‑friendly configuration, CI/CD templates, deployment helpers, and battle‑tested defaults that deliver a polished developer experience out of the box.

Features

• ✨ Split settings: settings/base.py, settings/development.py, settings/production.py
• 🏗️ Three structure types: Standard Django layout, Predefined structure, or Unified structure
• 🧱 Flexible app layout: Flat or nested apps package (e.g., apps/)
• 🧩 Complete app scaffolding: URLs, serializers, routes, views, models, admin, tests
• 🔗 Auto-wired URLs: Project URLs automatically include your apps
• 🧰 Essential utility files: .gitignore, README.md, .env.sample, requirements.txt, pyproject.toml
• 🚀 Deployment helpers: Justfile, Procfile, runtime.txt
• 🛠️ CI/CD templates: GitHub Actions and/or GitLab CI workflows
• 🔐 Secret key generator: Generate secure Django secret keys
• 🎨 Polished UX: Beautiful interactive interface with rich library
• 📦 App management: Add apps to existing projects with automatic settings configuration

Installation

Using pipx (recommended):

pipx install djinitx

Using pip:

pip install djinitx

Using uv:

uv tool install djinitx

From source:

git clone https://github.com/S4NKALP/djinit
cd djinit
pip install -e .

Requirements: Python 3.13+

Quick Start

Run the interactive setup:

djinit setup
# or
dj setup

The interactive setup will guide you through:

1. Structure Type Selection:

   • Standard structure (default Django layout)
   • Predefined structure (apps/users, apps/core, api/ layout)
   • Unified structure (core/, apps/core, apps/api layout)

2. Project Configuration:

   • Project directory (or use current directory with .)
   • Django project name (used for the config module)
   • Apps layout (flat vs nested package like apps/)
   • App names (comma‑separated)

3. CI/CD Configuration:

   • GitHub Actions only
   • GitLab CI only
   • Both (GitHub Actions + GitLab CI)
   • None (skip CI/CD)

4. Database Configuration:

   • Use DATABASE_URL (recommended for production)
   • Use individual database parameters

Commands

Setup Command

Launch the interactive project generator:

djinit setup
# or
dj setup

App Command

Create one or more Django apps in an existing project:

djinit app <names>
# or
dj app <names>

Examples:

• djinit app users or dj app users
• djinit app users,products,orders or dj app users,products,orders
• djinit app users products orders or dj app users products orders

The app command automatically:

• Creates the app with all necessary files
• Adds the app to INSTALLED_APPS in settings/base.py
• Configures URLs if using predefined structure
• Detects and respects your project's structure (nested/flat)

Secret Command

Generate secure Django SECRET_KEY values:

djinit secret [--count N] [--length L]
# or
dj secret [--count N] [--length L]

Examples:

• djinit secret - Generate 3 keys with default length (50)
• djinit secret --count 5 --length 50 - Generate 5 keys of length 50
• dj secret --count 10 --length 64 - Generate 10 keys of length 64

Project Structure Types

Standard Structure

The default Django layout with split settings:

project_name/
├── manage.py
├── project_name/
│   ├── __init__.py
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
├── apps/              # Optional nested apps
│   └── <app_name>/
│       ├── urls.py
│       ├── serializers.py
│       ├── routes.py
│       └── ...
└── <app_name>/        # Or flat apps
    └── ...

Predefined Structure

A production-ready structure with apps/ and api/ packages:

project_name/
├── manage.py
├── config/             # Django config module
│   ├── settings/
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   └── urls.py
├── apps/
│   ├── users/          # Pre-configured users app
│   │   ├── models/
│   │   ├── serializers/
│   │   ├── views/
│   │   ├── services/
│   │   └── tests/
│   └── core/           # Core utilities
│       ├── exceptions.py
│       ├── utils/
│       ├── mixins/
│       └── middleware/
└── api/
    ├── urls.py
    └── v1/
        └── urls.py

Unified Structure

A unified structure with core/ as the main module:

project_name/
├── manage.py
├── core/               # Main Django config
│   ├── settings/
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
└── apps/
    ├── core/           # Core app with models, utils
    │   ├── models/
    │   └── utils/
    └── api/            # API app
        └── ...

What Gets Generated

Core Files

• Django project structure with split settings
• Settings package: base.py, development.py, production.py
• Project URLs: Auto-configured with app includes
• WSGI/ASGI: Production-ready application entry points
• manage.py: Django management script

App Files

Each app includes:

• urls.py - URL routing
• serializers.py - DRF serializers
• routes.py - API route definitions
• views.py - View classes
• models.py - Database models
• admin.py - Admin configuration
• tests.py - Test structure
• apps.py - App configuration
• migrations/ - Migration directory

Utility Files

• .gitignore - Comprehensive Python/Django gitignore
• README.md - Project documentation template
• .env.sample - Environment variables template (includes SECRET_KEY placeholder, DATABASE_URL or individual DB params, email settings)
• requirements.txt - All necessary dependencies
• pyproject.toml - Modern Python project configuration (includes ruff linting/formatting config)
• Justfile - Development commands (migrations, server, etc.) using uv run
• Procfile - PaaS deployment configuration (Heroku, Railway, Render, etc.) with release task for migrations
• runtime.txt - Python version specification

CI/CD Files

• .github/workflows/ci.yml - GitHub Actions workflow (if selected)
• .gitlab-ci.yml - GitLab CI configuration (if selected)

Included Packages

The generated requirements.txt includes:

• Django - Web framework
• python-dotenv - Environment variable management
• django-jazzmin - Modern Django admin interface
• djangorestframework - REST API framework
• djangorestframework_simplejwt - JWT authentication (note: underscore in package name)
• drf-spectacular - OpenAPI 3.0 schema generation
• django-cors-headers - CORS handling
• whitenoise - Static file serving for production
• psycopg2-binary - PostgreSQL adapter
• gunicorn - Production WSGI server
• dj-database-url - Database URL parsing (when using DATABASE_URL)

This gives you a complete stack with:

• REST API with DRF
• JWT authentication endpoints: /token/, /token/refresh/, /token/blacklist/
• OpenAPI documentation at /docs/ and /schema/ (available in DEBUG mode only)
• CORS support (configured for localhost:3000 in development)
• Production-ready static file handling with WhiteNoise
• PostgreSQL support (SQLite in development by default)

Environment and Database

Environment Variables

A .env.sample file is generated with:

• DJANGO_SETTINGS_MODULE - Settings module path
• SECRET_KEY - Placeholder for your secret key (use djinit secret to generate)
• ALLOWED_HOSTS - Comma-separated list of allowed hosts
• Database configuration (either DATABASE_URL or individual DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT)
• Email settings (SMTP configuration)

Database Configuration

Development (Default)

• Uses SQLite (db.sqlite3) for local development
• No database configuration needed

Production

Option 1: DATABASE_URL (Recommended)

If you opt into DATABASE_URL, the production settings use dj-database-url:

DATABASE_URL=postgres://user:password@host:port/database

Option 2: Individual Parameters

Traditional Django database configuration with separate environment variables:

• DB_NAME - Database name
• DB_USER - Database user
• DB_PASSWORD - Database password
• DB_HOST - Database host
• DB_PORT - Database port

Development Workflow

After setup, use the generated Justfile for common tasks (uses uv by default):

just dev              # Start development server (uv run python manage.py runserver)
just migrate          # Run migrations
just makemigrations   # Create migrations
just shell            # Django shell
just test             # Run tests
just format           # Format code with ruff
just lint             # Lint code with ruff
just setup            # Complete setup (uv sync + migrate + createsuperuser)
just server           # Start production server with gunicorn

Note: The Justfile uses uv run for all commands. If you're not using uv, you can modify the Justfile or use Django commands directly.

API Endpoints

The generated project includes:

• Admin: /admin/
• JWT Authentication:
  • /token/ - Obtain access token
  • /token/refresh/ - Refresh access token
  • /token/blacklist/ - Blacklist refresh token
• API Documentation (DEBUG mode only):
  • /docs/ - Swagger UI
  • /schema/ - OpenAPI schema

Settings Configuration

• Base Settings (settings/base.py):

  • DRF configuration with JWT authentication
  • CORS settings
  • WhiteNoise for static files
  • Security headers
  • Pagination (20 items per page)

• Development Settings (settings/development.py):

  • SQLite database
  • DEBUG = True
  • Console email backend
  • CORS allows all origins
  • Generated secret key (replace in production)

• Production Settings (settings/production.py):

  • PostgreSQL database (via DATABASE_URL or individual params)
  • DEBUG = False
  • Security settings (HTTPS redirect, HSTS, secure cookies)
  • SMTP email configuration
  • Secret key from environment variable

Contributing

Contributions are welcome! Please:

1. Open an issue for bugs or feature ideas
2. Fork the repository
3. Create a feature branch
4. Submit a pull request with a clear description

Acknowledgments

• Django and the Django community
• Jinja2 - Template engine
• rich - Beautiful terminal output
• click - CLI framework
• ruff - Fast Python linter and formatter

License

MIT © Sankalp Tharu