Chapter 1: Getting Started & Project Setup

Multi-tenant Django foundation with Stripe billing, custom user model, and production-hardened settings — launch your SaaS in days.

What You Get

• Custom User model — Email-based auth with roles, built from AbstractBaseUser
• Multi-tenant architecture — Subdomain-based tenant resolution with shared database
• Stripe billing — Plans, subscriptions, invoices, and webhook handling
• Production settings — Whitenoise, S3 storage, Sentry, secure cookies, HSTS
• REST API — Django REST Framework with JWT auth and OpenAPI docs
• Docker-ready — Gunicorn, PostgreSQL, Redis, Celery worker
• HTMX + Alpine.js — Modern server-rendered frontend without SPA complexity
• Split settings — Base / development / production configuration pattern

File Tree

django-saas-boilerplate/
├── config/
│   ├── settings/
│   │   ├── base.py              # Shared Django settings
│   │   ├── development.py       # Dev overrides
│   │   └── production.py        # Production hardening
│   └── urls.py                  # Root URL configuration
├── apps/
│   ├── accounts/
│   │   ├── models.py            # Custom User model
│   │   ├── serializers.py       # DRF serializers
│   │   ├── views.py             # Auth & profile ViewSets
│   │   └── urls.py              # Account routes
│   ├── tenants/
│   │   ├── models.py            # Tenant & plan models
│   │   └── middleware.py        # Subdomain → tenant
│   └── billing/
│       ├── models.py            # Subscription & Invoice
│       └── webhooks.py          # Stripe webhook handler
├── templates/
│   └── base.html                # HTMX + Alpine.js base
├── docker/
│   ├── Dockerfile               # Multi-stage Django build
│   └── docker-compose.yml       # Full stack
├── manage.py
└── manifest.json

Requirements

• Python 3.11+
• PostgreSQL 15+
• Redis 7+ (for Celery task queue)
• Stripe account (for billing features)

Chapter 2: Configuration & Running

Clone and configure

cp .env.example .env
# Set DATABASE_URL, SECRET_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET

Run with Docker

docker compose -f docker/docker-compose.yml up -d
docker compose exec app python manage.py migrate
docker compose exec app python manage.py createsuperuser

Or run locally

pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Create a tenant

from apps.tenants.models import Tenant, Plan

plan = Plan.objects.create(
    name="Starter",
    stripe_price_id="price_xxx",
    max_users=5,
    monthly_price_cents=2900,
)

tenant = Tenant.objects.create(
    name="Acme Corp",
    subdomain="acme",
    plan=plan,
    owner=user,
)
# Access at: https://acme.yourdomain.com

Set up Stripe webhooks

# Local development with Stripe CLI
stripe listen --forward-to localhost:8000/api/v1/billing/webhook/

# Production: configure webhook URL in Stripe dashboard
# https://yourdomain.com/api/v1/billing/webhook/