django-saas-starter

A production-ready Cookiecutter template for building Django SaaS apps fast.

• Stack: Django 6.0.5 + Python 3.14.5 + Tailwind + HTMX + Alpine.js
• Pragmatic defaults: auth, payments (optional), email, API, landing pages, and optional pages-owned blog/docs content
• Deployment-ready: Docker Compose (local + prod), Render, Fly.io, GitHub Actions (CapRover), and optional DigitalOcean App Platform

Quickstart

cookiecutter git@github.com:rasulkireev/django-saas-starter.git

Then follow the generated project’s README.md for local development + deployment.

Important: in generated projects, run uv run python manage.py makemigrations (without app labels) before feature work so all app model changes are captured.

What you get (high level)

Core

• ✅ Django 6.0.5
• ✅ Python 3.14.5
• ✅ Environment variables via django-environ

Auth

• ✅ User auth via django-allauth
• ✅ Passkey sign in + sign up via django-allauth MFA with email-code verification
• ✅ Passkey MFA with recovery-code fallback
• ❓ Social auth via django-allauth
  • ❓ Google (preconfigured)
  • ❓ GitHub (preconfigured)

Frontend

• ✅ Node.js 24.15.0 LTS for frontend builds
• ✅ Tailwind CSS for styling
• ✅ HTMX for server-rendered UI interactions
• ✅ Alpine.js for local browser state
• ✅ Minimal Tailwind CLI/staticfiles asset pipeline
• ✅ Optional keyboard shortcut navigation, enabled by default
• ✅ SEO-friendly templates (meta tags, JSON-LD schema, OG images)
• ✅ Bundled .agents/skills/frontend-ui-quality guidance for generated Django/Tailwind UI quality checks
• ✅ Bundled .agents/skills/django-htmx guidance for AI agents working on Django-native interactivity
• ✅ Root DESIGN.md based on Google Labs Code's DESIGN.md format for tool-neutral human/AI design guidance

Pages & content

• ✅ Landing + pricing + auth pages + sitemap
• ❓ User-facing blog managed by the Pages app
• ❓ User-facing docs content managed by the Pages app

API

• ✅ API foundation via django-ninja
• ✅ Auth modes included (session, token, superuser)

Database & storage

• ✅ Postgres 18 Docker images preconfigured
• ✅ Redis 8.6.3 Docker image preconfigured
• ✅ pgvector enabled
• ✅ pg_stat_statements enabled
• ❓ S3-compatible media storage (includes Minio for local + prod)

Email & communication

• ✅ Email via Anymail + Mailgun (Mailhog for local)
• ✅ Styled UI message component
• ❓ MJML for email templating
• ❓ Apprise for internal/admin notifications to Slack or other channels

Dev experience

• ✅ Python dependency management with uv and a generated uv.lock
• ✅ Docker Compose (local + prod)
• ✅ Terminal-first local development path without Docker for humans and AI agents
• ✅ Agent-friendly Compose service targets with configurable local ports for multi-repo work
• ✅ PGSandbox MCP guidance for disposable local Postgres testing from AI agents
• ✅ Fly.io app config (fly.toml) with web + worker process groups
• ✅ Makefile helpers
• ✅ pytest
• ✅ Pre-commit: ruff + djlint
• ✅ Lockfile-backed npm installs and frontend linting in generated CI
• ✅ Generated CI split into parallel Python quality, frontend, and pytest jobs with pytest-only settings for local cache/media/task isolation
• ✅ Generated docs/quality.md command matrix plus Makefile quality targets for local CI and touched-area checks
• ✅ Generated high-risk coverage reporting target with a configurable COVERAGE_FAIL_UNDER baseline
• ✅ pyscn static analysis Makefile targets + CI gate
• ✅ Automated deploy to CapRover via GitHub Actions
• ❓ Automated deploy to DigitalOcean App Platform via .do/app.yaml + GitHub Actions
• ❓ Optional CI workflow (runs pre-commit, ESLint, frontend build, pyscn, Django checks, and pytest on PRs and pushes to main)

Observability & analytics

• ✅ Python stdlib logging (console in dev, structured JSON in prod)
• ✅ Canonical privacy-aware request/job/domain event fields for APM portability
• ❓ Sentry
• ❓ Healthcheck endpoint
• ❓ PostHog product analytics and batched OTLP log export

AI

• ✅ Tool-neutral DESIGN.md design source of truth for humans and AI coding agents
• ✅ Tool-neutral AGENTS.md workflow for coding agents
• ✅ Tool-neutral generated docs/quality.md local CI and touched-area command contract for humans and AI coding agents
• ✅ Cross-agent frontend UI quality workflow for generated Django templates, Tailwind CSS, responsive states, accessibility, motion, and design-system alignment
• ✅ Cross-agent local development workflow for no-Docker terminal, service-backed, and multi-repo agent work
• ✅ Repo-scoped .agents/skills/django-htmx workflow for HTMX with Django templates, forms, and Alpine.js coordination
• ✅ Nested AGENTS.md guidance for generated Pages app content
• ✅ Cross-agent Alpine.js skill for Django templates and HTMX coordination
• ✅ Cross-agent Django Ninja skill for API endpoints, schemas, routers, authentication, OpenAPI docs, and tests
• ✅ Cross-agent Django Q2 skill for background tasks, schedules, workers, Redis, and ORM broker fallback
• ✅ Cross-agent PGSandbox MCP skill for disposable local Postgres checks with DATABASE_URL
• ✅ Cross-agent agent reliability workflow, task templates, code tours, and eval seed docs for repeatable AI-assisted implementation and verification
• ❓ Pydantic AI via OpenRouter for in-app agents
• ❓ Cross-agent Pydantic AI skills from pydantic/skills, gated by use_ai
• ❓ OpenRouter model presets via OPENROUTER_MODEL_FAST and OPENROUTER_MODEL_SMART

Philosophy

This template aims to be:

• Boring to maintain (standard Django patterns, explicit config)
• Fast to ship (common SaaS pieces already wired)
• Easy to extend (clear app boundaries and sensible defaults)

Contributing

Issues and PRs are welcome. If you’re proposing a bigger change, open an issue first so we can align on scope.

Running template tests

This repo includes pytest-based tests that generate a project via Cookiecutter and assert the expected files are present/removed for various options.

uv run --group test pytest