Why djsuite?

Every production Django project needs the same foundation: DRF, JWT auth, Celery workers, PostgreSQL, Docker, CI/CD pipelines, and deployment config. Setting this up by hand takes hours and inevitably drifts between projects.

djsuite solves this. One command generates ~50 files with a proven structure — and when the template evolves, --update-* flags push changes to existing projects without touching your custom code.

Install

pip install djsuite

Or with pipx (recommended for CLI tools):

pipx install djsuite

Quick Start

# Create a new project
djsuite myproject --description "Payments API"

# Preview what would be created
djsuite myproject --dry-run

# List all generated files
djsuite --list-files

  created .env
  created .github/workflows/ci.yml
  created .github/workflows/dev-cd.yml
  created Dockerfile
  created main/settings.py
  created base/models.py
  ... (~50 files total)

Running pdm lock to pin dependencies...
  pdm.lock created

Project myproject created at /home/you/myproject

Next steps:
  cd myproject
  pdm install
  cp .env .env.local  # edit with your settings
  pdm run migrate
  pdm run startdev 8000

What You Get

Stack

Generated Project Structure

myproject/
├── .djsuite.json                      # djsuite metadata (for update mode)
├── .env                              # Environment variables
├── .pre-commit-config.yaml           # black + isort hooks
├── docker-compose.yml                # Postgres + Redis for local dev
├── pyproject.toml                    # PDM project with all dependencies
├── Dockerfile                        # Multi-stage build (non-root user)
├── README.md                         # Project docs with architecture guide
├── CONTRIBUTING.md                   # Contributor guide
├── CHANGELOG.md                      # Auto-updated on production deploy
├── .github/
│   ├── copilot-instructions.md       # AI assistant context
│   ├── release.yml                   # Release note categories
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/
│       ├── ci.yml                    # Lint + test on every PR
│       ├── auto-label.yml            # Label PRs from branch prefix
│       ├── dev-cd.yml                # Deploy to dev + draft release
│       └── prod-cd.yml              # Deploy to prod + publish release
├── main/                             # Django project config
│   ├── settings.py                   # Env-based config with security defaults
│   ├── celery.py                     # Celery app
│   ├── urls.py                       # API routes + Swagger UI
│   └── wsgi.py / asgi.py
├── base/                             # Shared foundation app
│   ├── containers.py                 # Dependency injection
│   ├── models.py                     # TimeStampMixin base model
│   ├── views.py                      # Health check + Celery task status
│   ├── services/                     # Service layer
│   └── tests/                        # Per-app tests
└── (deployment files)                # entrypoint, nginx, supervisor, EB hooks

Architecture Highlights

• Service layer pattern — business logic in services/, not in views or serializers
• Dependency injection — services wired through dependency-injector, mock-friendly testing
• Health check — /health/ endpoint checks DB connectivity (200/503)
• Security defaults — HSTS, secure cookies, SSL redirect auto-enabled in production
• Trunk-based CD — branch prefix drives labels, changelogs, and deployments automatically
• Non-root Docker — container runs as unprivileged user with Nginx security headers

CLI Reference

Create Mode

djsuite <project_name> [OPTIONS]

Update Mode

Push template improvements to an existing project without overwriting your custom code (main/ and base/ are never touched by updates).

djsuite --update-ci --project-dir ./myproject       # CI/CD workflows
djsuite --update-docker --project-dir ./myproject    # Docker files
djsuite --update-infra --project-dir ./myproject     # Infrastructure files
djsuite --update-all --project-dir ./myproject       # Everything updatable
djsuite --update-all --no-backup --project-dir ./myproject  # Skip backup

Before overwriting, djsuite shows a diff summary and creates a timestamped backup in .djsuite-backup/:

Updating 4 file(s) in /home/you/myproject:

  [CHANGED] (+12/-3 lines)        .github/workflows/ci.yml
  [UNCHANGED]                      .github/workflows/dev-cd.yml
  [NEW]                            .github/copilot-instructions.md

Backed up 1 file(s) to .djsuite-backup/20250211_143022
Updated 2 file(s).

--update-all = CI + Docker + Infra + Root. The main/ and base/ apps are never updated — they belong to you.

Platform Support

The platform is stored in .djsuite.json, so --update-* commands automatically use the correct platform. See Contributing for how to add a new platform.

How It Works

templates/
├── common/              # Platform-agnostic Django scaffolding
│   ├── main/            #   settings.py, celery.py, urls.py, wsgi.py, ...
│   ├── base/            #   models, views, DI container, pagination, ...
│   ├── github/          #   CI workflow, copilot instructions, release config
│   └── (root files)     #   .env, pyproject.toml, manage.py, ...
└── platforms/
    └── aws_eb/          # EB-specific deployment infra
        ├── github/workflows/   dev-cd.yml, prod-cd.yml
        ├── platform/hooks/     EB lifecycle hooks
        ├── nginx/              reverse proxy configs
        └── (root files)        Dockerfile, entrypoint, supervisord, ...

1. Manifest merges common + platform files into a single file map
2. Renderer processes .j2 files through Jinja2, copies static files verbatim
3. Generator writes rendered files, sets +x on scripts, writes .djsuite.json, runs pdm lock
4. Updater reads .djsuite.json, re-renders selected groups, shows diffs, creates backups

CI/CD Setup

CI runs on every pull request with zero configuration — no GitHub Secrets needed.

CD (AWS EB) requires two repository secrets for deployment:

The CD workflows authenticate via OIDC federation — no static AWS keys. Create an IAM role named GHA-EB-Deploy with Elastic Beanstalk, ECR, and S3 permissions, and configure its trust policy for GitHub Actions.

Releasing

1. Trigger the Release workflow manually via GitHub Actions (workflow_dispatch)
2. The workflow computes the next semver from PR labels since the last tag:
   • breaking label → major bump
   • feature label → minor bump
   • fix, chore, docs → patch bump
3. Tests run, package is built and published to PyPI
4. A GitHub release is created with categorized notes
5. pyproject.toml, __init__.py, and CHANGELOG.md are updated automatically

Requires PyPI trusted publishing configured for this repository.

Contributing

See CONTRIBUTING.md for setup instructions, project structure, and how to add templates or platforms.

License

MIT