django-forge 🔨
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.
uv tool install forge-django
forge-django start myproject
About this repository
This repository contains two things:
django_forge/— the forge CLI tool and its Jinja2 template tree (the scaffolder itself).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 | 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 |
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.