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

The boilerplate separates settings by environment so local convenience never weakens production security. config/settings/base.py contains shared apps, middleware, REST Framework, PostgreSQL, Redis, Stripe, and path settings. development.py imports the base module and enables debug tooling; production.py adds secure cookies, HSTS, Whitenoise, S3, Redis caching, and Sentry. This explicit import pattern provides the same benefit as django-split-settings without another dependency. Set the module when starting Django:

export DJANGO_SETTINGS_MODULE=config.settings.development
python manage.py runserver

# Production processes use:
export DJANGO_SETTINGS_MODULE=config.settings.production

Environment variables

Copy .env.example to .env, keep it out of version control, and provide at least SECRET_KEY, database credentials, Stripe keys, and REDIS_URL. The supplied settings use os.environ; teams that prefer typed values can add django-environ (or use equivalent python-decouple calls):

# config/settings/base.py
import environ

env = environ.Env(DEBUG=(bool, False))
environ.Env.read_env(BASE_DIR / ".env")  # local only

SECRET_KEY = env("SECRET_KEY")
DEBUG = env.bool("DEBUG")
DATABASES = {"default": env.db("DATABASE_URL")}
STRIPE_SECRET_KEY = env("STRIPE_SECRET_KEY", default="")

Never give production secrets a usable default. In hosted environments, inject them through the platform’s secret manager rather than shipping an .env file.

Lists need deliberate parsing. For example, split ALLOWED_HOSTS and CORS_ALLOWED_ORIGINS on commas, strip whitespace, and reject empty production values. Boolean strings also need typed conversion: Python treats the nonempty string "false" as true. Fail during startup when a required value is absent, so a broken release never reaches customer traffic.

Database configuration

PostgreSQL is the production target and the default bundled backend. For local parity, run PostgreSQL through Docker and use DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, and DB_PORT. SQLite is acceptable for quick UI work, but it will not expose PostgreSQL-specific locking, indexing, or concurrency behavior:

# config/settings/development.py
if os.environ.get("USE_SQLITE") == "1":
    DATABASES = {
        "default": {
            "ENGINE": "django.db.backends.sqlite3",
            "NAME": BASE_DIR / "db.sqlite3",
        }
    }

Run migrations whenever models or branches change: python manage.py migrate. Use PostgreSQL in CI before merging database-sensitive work.

Static files and uploads

STATIC_ROOT receives collected assets; MEDIA_ROOT stores local uploads during development. In production, Whitenoise serves versioned static assets from the application image, while django-storages sends private user uploads to S3:

MIDDLEWARE.insert(1, "whitenoise.middleware.WhiteNoiseMiddleware")
STATICFILES_STORAGE = (
    "whitenoise.storage.CompressedManifestStaticFilesStorage"
)
DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"
AWS_DEFAULT_ACL = "private"

Run python manage.py collectstatic --noinput during the image build. Do not serve customer uploads through Whitenoise; use short-lived signed S3 URLs.

Local and production processes

For a native setup, install requirements, start PostgreSQL and Redis, migrate, then run python manage.py runserver. The bundled Compose stack is closer to production:

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

runserver is development-only. The Docker image should start Gunicorn behind Nginx, Cloudflare, or the hosting load balancer:

gunicorn config.wsgi:application --bind 0.0.0.0:8000 \
  --workers 3 --timeout 60 --access-logfile -

Before routing traffic, run python manage.py check --deploy, apply migrations as a release step, collect static files, and verify /admin/, API authentication, Redis/Celery, and the Stripe webhook endpoint. Terminate TLS at the proxy and forward X-Forwarded-Proto; the production settings already enforce HTTPS and secure cookies.