Skip to main content

django-forge 🔨

django-forge logo

Ask 3 questions. Get a production-ready Django project.

forge-django scaffolds complete, immediately runnable Django projects with senior-architect best practices — custom User model, allauth auth, ruff + ty (Astral's type checker) tooling, GitHub Actions CI/CD, and your choice of API framework, database, and 11 optional layers. All in under a minute.

CI

uv tool install forge-django
forge-django start myproject

About this repository

This repository contains two things:

  1. django_forge/ — the forge CLI tool and its Jinja2 template tree (the scaffolder itself).
  2. site/ — the project's landing page, a Svelte 5 + Vite single-page site deployed to GitHub Pages: https://k1lgor.github.io/django-forge/

Both live in this repo and are tested separately: the tooling CI runs on django_forge/ + tests/ changes, and a dedicated workflow deploys the site whenever site/ changes. See Repository layout.

Quick start

uv tool install forge-django   # install the CLI
forge-django start myproject   # answer 3 questions
cd myproject
uv run manage.py runserver     # start developing

forge-django start runs uv sync, creates migrations, migrates the database, and runs check --deploy — your project is runnable the moment the success banner prints.

The wizard

forge-django asks three questions and confirms your choices before generating anything. Every option is listed below.

1 · API Framework

# Option What you get
1 DRF — Django REST Framework The classic choice. Mature, large ecosystem, serializer-based. JWT auth (djangorestframework-simplejwt), browsable API, filtering.
2 Django-Ninja Modern, type-hint native, Pydantic-based. ~5x faster request handling than DRF. JWT auth, OpenAPI docs, async views. Recommended for new projects.
3 Pure Django No API framework. Traditional Django views + templates. Best for server-rendered apps and admin-heavy projects. Session-based auth via allauth.

2 · Database

# Option What you get
1 PostgreSQL (prod) + SQLite (dev) Production-ready Postgres configuration via DATABASE_URL, with SQLite for fast local development.
2 SQLite only Simpler setup, no PostgreSQL dependency.

3 · Optional layers (multi-select — comma-separated numbers, or 0 for none)

# Layer Description
1 Docker Multi-stage build + Compose
2 Celery Background task queue (Redis required)
3 Email Mailpit (a local SMTP test inbox, for dev) / SMTP (prod)
4 Caching Redis cache backend
5 Social Auth Google + GitHub OAuth via allauth
6 S3 Storage S3/MinIO (S3-compatible object storage) static + media files
7 Health Check /healthz endpoint for load balancers
8 Audit Trail Record every model change (django-simple-history)
9 Backup Nightly DB backups (django-dbbackup)
10 Seed Data Factory-based dev data seeding
11 Preflight Pre-deploy safety checks command

The wizard looks like this — real output of forge-django start myproject (captured by declining the final confirmation, so no files are written):

=== FORGE v0.4.0 - django project scaffolder ===

  Forge your Django project:  myproject

  API Framework
  1. DRF
     Django REST Framework - battle-tested, large ecosystem
  2. Django-Ninja
     Modern, type-hint native, ~5x faster
  3. Pure Django
     Templates + views, no API framework
  Which API framework? (1-3) (1):
  Database
  1. PostgreSQL (production) + SQLite (development)
     Production-ready, SQLite for fast local dev
  2. SQLite only
     Simpler setup, no PostgreSQL dependency
  Which database? (1-2) (1):
  Optional Layers
  1. ○ Docker
     Multi-stage build + Compose
  2. ○ Celery
     Background task queue (Redis required)
  3. ○ Email
     Mailpit (dev) / SMTP (prod)
  4. ○ Caching
     Redis cache backend
  5. ○ Social Auth
     Google + GitHub OAuth via allauth
  6. ○ S3 Storage
     S3/MinIO static + media file storage
  7. ○ Health Check
     /healthz endpoint for load balancers
  8. ○ Audit Trail
     Record every model change (django-simple-history)
  9. ○ Backup
     Nightly DB dumps (django-dbbackup)
  10. ○ Seed Data
     Factory-based dev data seeding
  11. ○ Preflight
     Pre-deploy safety checks command
  Select optional layers (comma-separated numbers, or 0 for none) (0):
───────────────────────────────────────

  Project:   myproject
  Framework: DRF - Django REST Framework
  Database:  PostgreSQL (prod) + SQLite (dev)
  Layers:    Docker, Celery

Looks good? [y/n] (y):

CLI reference

Command Description
forge-django start <project-name> Create a new Django project. Interactive wizard, or --no-input for defaults.
forge-django list Show all available frameworks, optional layers, and core layers.
forge-django add <layer> Add an optional layer to an existing project (works for all 11).
forge-django upgrade Re-apply the latest templates to an existing project.
forge-django --version / -V Print the installed version.
forge-django --help / -h Show help. forge-django with no arguments also shows help.

forge-django start flags

Flag Description
--no-input Skip all prompts and use sensible defaults (DRF, PostgreSQL + SQLite, no layers). Auto-activates in CI.

forge-django add behavior

Runs from inside an existing project. It:

  • validates the layer name (docker, celery, email, cache, social, storage, healthcheck, audit, backup, seed, preflight),
  • detects the project from .forge.toml ("Not a forge project" otherwise),
  • skips layers that are already installed,
  • lists every file it will overwrite and asks for confirmation,
  • and preserves your existing layers and settings.

Optional layers (all 11)

Layer What it adds Deps
Docker Multi-stage Dockerfile (uv build), compose.yaml with app + db + optional redis/mailpit, .dockerignore, gunicorn wired into the image gunicorn~=23.0
Celery config/celery.py, apps/accounts/tasks.py, Redis broker + cache settings, worker-ready __init__.py celery~=5.6.0, redis>=5.0
Email Mailpit (dev) / SMTP (prod) settings, email env vars in .env.example, Mailpit Compose service —
Caching Redis cache backend (django.core.cache.backends.redis.RedisCache) redis>=5.0
Social Auth SOCIALACCOUNT_PROVIDERS for Google + GitHub, provider env vars —
S3 Storage STORAGES pointing at storages.backends.s3.S3Storage, AWS_* settings + env vars, S3 media URL django-storages[s3]
Health Check django-health-check at /healthz/ — DB check always, cache/broker checks when those layers exist django-health-check~=3.18
Audit Trail django-simple-history — HistoricalRecords on the User model, HistoryRequestMiddleware, SimpleHistoryAdmin django-simple-history
Backup django-dbbackup — dumps to S3 when the storage layer is present, else backups/; make backup / make restore django-dbbackup
Seed Data factory-boy UserFactory + manage.py seed, make seed factory-boy (dev)
Preflight manage.py preflight — check --deploy, pending-migrations check, migrate --check; make preflight —

Core layers (always included)

Layer What's included
Python tooling uv, pyproject.toml, Python 3.12+
Linting & types ruff (linter + formatter), ty (type checker)
Testing pytest, pytest-django, coverage, factory_boy
Auth Custom User model (email login), django-allauth, JWT or session
Database PostgreSQL (prod) + SQLite (dev), migration defaults
Async ASGI via uvicorn, async views, async ORM support
CI/CD GitHub Actions: lint, type-check, test
Admin Custom User admin
Logging Structured logging
Static/media WhiteNoise, django-storages-ready
Security CORS headers, env-based secrets, HSTS in production

What a generated project looks like

myproject/
├── manage.py
├── pyproject.toml          # deps, ruff, ty, pytest configured
├── Makefile                # see commands below
├── .env.example            # all environment variables documented
├── .gitignore              # .env ignored, .env.example tracked
├── .forge.toml             # layer tracking — read by forge-django add/upgrade
├── .forge-manifest.json    # ownership ledger: sha256 of every file forge generated
├── .pre-commit-config.yaml
├── config/
│   ├── settings/           # base.py, dev.py, prod.py (split correctly)
│   ├── urls.py, wsgi.py, asgi.py
│   └── celery.py           # (with the Celery layer)
├── apps/accounts/          # custom User, allauth, views, admin, signals
│   ├── factories.py        # (with Seed Data)
│   └── management/commands/  # seed.py, preflight.py (layers)
├── templates/              # base.html + accounts/* (Pure Django)
├── tests/                  # pytest-django wired
├── static/, media/
├── Dockerfile, compose.yaml, .dockerignore   # (with Docker)
└── .github/workflows/ci.yml

Makefile commands (generated project)

Command Description
make lint Run ruff linter + formatter check
make typecheck Run ty type checker
make test Run pytest
make check lint + typecheck + test
make run manage.py runserver
make migrate / make makemigrations Database management
make seed Create sample users (Seed Data layer)
make preflight Pre-deploy checks (Preflight layer)
make backup / make restore DB dumps / restore (Backup layer)

Environment variables

Variable Purpose
DJANGO_SECRET_KEY Cryptographic signing key (env-driven via pydantic-settings)
DJANGO_SETTINGS_MODULE config.settings.base by default
DJANGO_DEBUG true in development, false in production
DATABASE_URL PostgreSQL URL in production
ALLOWED_HOSTS Comma-separated hostnames (env-driven, never hardcoded *)
CORS_ALLOWED_ORIGINS Comma-separated allowed origins
DOCKER true when running in Docker (Docker layer)
MAILPIT_SMTP_HOST / _PORT / MAILPIT_API_URL Mailpit (Email layer)
EMAIL_HOST / EMAIL_PORT / EMAIL_HOST_USER / EMAIL_HOST_PASSWORD SMTP (Email layer)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET Google OAuth (Social Auth layer)
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET GitHub OAuth (Social Auth layer)
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_STORAGE_BUCKET_NAME / AWS_S3_ENDPOINT_URL / AWS_S3_REGION_NAME S3/MinIO (S3 Storage layer)

Adding layers later — forge-django add

Already have a project? Run forge-django add <layer> from its root directory — works for all 11 layers.

cd myproject
forge-django add docker      # Dockerfile + compose.yaml + .dockerignore
forge-django add healthcheck # /healthz endpoint
forge-django add backup      # nightly DB dumps

forge-django upgrade

Re-applies the latest templates to an existing project. It reads your .forge.toml, lists every file it would overwrite, and asks for confirmation before touching anything.

Your edits survive. Every generated file is hashed into a .forge-manifest.json. On forge-django add / forge-django upgrade, the CLI refreshes files it still owns and skips files you modified, byte for byte — and the SECRET_KEY is read back from your project instead of being regenerated.

Automation

--no-input skips all prompts and uses sensible defaults (DRF, PostgreSQL + SQLite, no layers). CI environments (CI=true, GITHUB_ACTIONS=true) auto-activate this mode — perfect for pipelines.

forge-django start myproject --no-input

Landing page

The landing page at https://k1lgor.github.io/django-forge/ is a terminal-styled single-page site built with Svelte 5 + Vite (~23 kB gzip JS, no images or fonts, no-JS fallback). It features a boot-sequence hero, an interactive forge simulator that builds a real project tree from the 3 wizard questions, and the 11 layers shown as expandable cards with the actual generated files.

cd site
npm install
npm run dev        # local dev at http://localhost:5173
npm run build      # static output in site/dist

The site deploys automatically to GitHub Pages whenever a push touches site/** (enable Pages in repo settings with "Source: GitHub Actions").

Repository layout

django_forge/          # the forge CLI package
├── cli/                # start, add, upgrade, list commands + installer
├── renderer.py         # Jinja2 engine + .forge-manifest.json ownership ledger
└── templates/          # the Jinja2 template tree for generated projects
site/                   # Svelte 5 landing page (GitHub Pages)
tests/                  # pytest suite
.github/workflows/
├── ci.yml              # tooling CI: ruff, ty, pytest (3 OS × 3 Python)
└── deploy-site.yml     # Pages deploy — triggers on site/ changes only

Development

uv sync                            # install dev tooling (the [dependency-groups] dev group)
uv run pytest                      # run the test suite
uv run ruff check .                # lint
uv run ruff format --check .       # formatting
uv run ty check django_forge       # type check

Contributions welcome — see CONTRIBUTING.md for the development loop, and report vulnerabilities privately as described in SECURITY.md.

Installation

uv tool install forge-django

Requires: Python 3.10+ for the CLI tool, Python 3.12+ for generated projects. Package manager: uv (install from astral.sh/uv).

License

MIT

Metadata

Release files for forge-django 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for forge-django 0.4.0
File Size Uploaded Provenance Actions
forge_django-0.4.0.tar.gz 106.3 kB With provenance Details for forge_django-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for forge-django 0.4.0
File Interpreter ABI Platform Actions
forge_django-0.4.0-py3-none-any.whl Python 3 none any Details for forge_django-0.4.0-py3-none-any.whl

Total release size: 176.3 kB

Release files / forge_django-0.4.0.tar.gz

Download URL forge_django-0.4.0.tar.gz
Size 106.3 kB
Tags Source
SHA-256 checksum
How to use checksums
2e447e6fee8a9be2fc3308e3cd916fe1840a42826a2e34323cddeb93b6889329
BLAKE2b-256 checksum
How to use checksums
96827039e7546c35aab49b266a69ab9c3d47218fc688af853b979c743a58bd52
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / forge_django-0.4.0-py3-none-any.whl

Download URL forge_django-0.4.0-py3-none-any.whl
Size 70.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
390f1d7151bafed6ddcb3bd12c9e50e2616d68c6eda04eb00d347125be7df3f1
BLAKE2b-256 checksum
How to use checksums
32ad0777a35ad61f4a06220decc12103c1880f5e3fdbe91cbc75f7067e92cb3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for forge-django 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for forge_django-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page