Django Base Site

Documentation: django-base-site.readthedocs.org
Source Code: github.com/epicserve/django-base-site

---

The Django Base Site is an opinionated starter template to jump-start any new Django project. It has been lovingly maintained for over twelve years and has been used to jump-start many other projects. Because it is organized logically, it will help you and your team collaborate and stay organized as your project grows. All the best practices and tools are used to help you save days of mundane setup and tooling! This Django boilerplate/starter template will help you or your team deploy your site to production in minutes instead of days.

To get started, jump to the installation section or keep reading to learn more about the included features.

✨ Features

🧑‍💻 Best Practices

• Epicenv - A delightful environment variable manager with schema validation, type coercion, and CLI tools for generating .env files. See the epicenv documentation for more details.
• Docker - Docker Compose for development with healthchecks on every service, plus a multi-stage Dockerfile for a production-ready image.
• Mailpit - Local SMTP capture with a web UI at http://localhost:8025
• MinIO - S3-compatible object storage for local media uploads (avatars, etc.) with a console at http://localhost:9001
• UV - Used to maintain Python requirements
• Just - Popular tool for running common commands (make equivalent)
• python-json-logger and readable-log-formatter - JSON logging for better log parsing

📦️ Django Packages

• Django 5 - Latest version of Django
• Custom User Model - Extends AbstractUser with per-user timezone (auto-detected from the browser via middleware) and avatar fields (uploaded to MinIO/S3 with crop data).
• Django Allauth (headless) - JSON auth API with full MFA support: TOTP, recovery codes, and WebAuthn passkeys (via fido2).
• Django Ninja - Fast type-safe API framework powering /api/app-context/, the user/avatar endpoints, organizations, teams, and the public invite flow.
• Django Hijack - Staff impersonation with a SPA-driven user search, gated by a staff_only permission check.
• Celery - Most popular task runner for running asynchronous tasks in the background.
• Gunicorn - Production WSGI server (4 workers × 2 threads), configured at gunicorn.conf.py.
• WhiteNoise - Serves Vite-hashed assets in production with Cache-Control: max-age=31536000, immutable.
• Django Storages + boto3 - S3-compatible media storage with a custom backend (apps.base.storage.S3MediaStorage) that handles the Docker-internal vs. browser endpoint URL split for MinIO.
• Django Alive - Health-check endpoints
• Django Maintenance Mode - Drop the site into a maintenance window.
• Django SES - Production email backend.

🏢 Multi-Tenant Scaffolding

• apps/organizations/ - Organization, OrganizationMember (with is_owner / is_primary flags), and OrganizationInvite models. OrganizationMiddleware lazy-loads request.org from the session; an org switcher lives in the user-menu navbar.
• apps/teams/ - generic Team model (organization FK + M2M users) with full CRUD ninja API.
• Server-rendered accept-invite flow lives in the SPA at /organizations/invite/:key/accept/ (works for anonymous visitors with sign-in / sign-up roundtrip via ?next=).

🔧 Python Testing Tools

• Pytest - The most popular Python test runner in the Python community
• Pytest Django - Django plugin for Pytest
• Pytest-cov - Code coverage
• Pytest Playwright - End-to-end tests live under e2e/ and run against a dedicated config.settings.e2e settings module with pre-built Vite assets.
• Model Bakery - Faster fixture creation
• Django Test Plus - Helper functions to write tests faster
• pyotp - Used in the MFA / TOTP test suite

🐛 Debugging Support

• Remote Debugging - Full debugging support for PyCharm, VS Code, LazyVim/Neovim, and any DAP-compatible editor
• One Command Setup - Start debugging with just start_with_debugpy
• PyCharm Integration - Native Docker Compose debugging support with hot-reload
• VS Code Integration - Pre-configured launch configurations and tasks
• Detailed Documentation - Complete setup guides for all supported editors

🩺 Code Quality, Formatting, and Linting Tools

• Ruff - Python formatting and linting (replaces Black and friends, written in Rust).
• Ty - Python type checking
• dj Lint - Automatic Django HTML template formatting and linting
• Django Debug Toolbar - Inspect query counts, settings, and templates in DEBUG.
• Eslint (flat config) with eslint-plugin-vue - JS/Vue linting

💄 Frontend

• Vue 3 SPA - Lazy-loaded routes via Vue Router 5, reactive app store, theme-applied-before-CSS to prevent flash, version watcher with deploy-update banner.
• Tailwind CSS v4 - Utility-first styling with the @tailwindcss/vite plugin and a custom dark variant driven by data-theme.
• Vite 8 - Frontend build tool. Hashed-asset cache + manifest support so WhiteNoise can serve them with immutable headers.
• bun - Fast JS toolchain (replaces npm). The frontend Docker service is built from oven/bun:1.
• @heroicons/vue, vue-advanced-cropper, reka-ui - UI primitives.
• Account settings (General, Email, Password change, Security with TOTP / recovery codes / passkeys), org settings (General, Members + Invites, Teams), Send-Test-Email and Impersonate views (superuser/staff).

📝 Documentation

The Django Base Site uses MkDocs for documentation. You can copy the config file and the docs directory to help jumpstart the documentation for your new project. The following are MkDocs plugins being used:

• MkDocs Material - Beautify MkDocs theme
• mkdocstrings - Build documentation from Python docstrings
• mkdocs-include-markdown-plugin - Include docs from other files
• mkdocs-linkcheck - Automatic link checking

Installation

Requirements

Before proceeding make sure you have installed Docker and Just. Docker with Docker Compose is used for local development and Just is used for common project commands.

Quickstart Install Script

Copy and paste the following into your terminal to run the install script:

bash <(curl -s https://raw.githubusercontent.com/epicserve/django-base-site/main/scripts/start_new_project)

Running the script mostly does the same thing as manual method. The exception is that the install script has questions to customize your new project setup.

Note: When starting the Django runserver it will take several seconds before the CSS styles take effect. This is because Vite is running in dev mode which takes a few seconds to take effect.

Example output:

$ cd ~/Sites
$ bash <(curl -s https://raw.githubusercontent.com/epicserve/django-base-site/main/scripts/start_new_project)

What is the project name slug [example]?
What directory do you want your project in [/Users/brento/Sites/example]?

Done.

To start Docker Compose run:
$ cd /Users/brento/Sites/example
$ just start

Manual Installation

$ curl -LOk https://github.com/epicserve/django-base-site/archive/main.zip && unzip main
$ mv django-base-site-main example
$ cd example
$ uvx epicenv create        # Generates .env from the schema in pyproject.toml
$ just clean_extra_files
$ find ./public -name ".keep" | xargs rm -rf
$ just start

epicenv create reads the [tool.epicenv.variables] block in pyproject.toml and produces a .env with sensible defaults — SECRET_KEY and POSTGRES_PASSWORD are auto-generated, SITE_DOMAIN=localhost:8000 (so passkeys work), and the MinIO + Mailpit credentials are pre-wired.

Usage

Dev URLs

Once just start is up, the following are available:

URL	What
http://localhost:8000/	Vue SPA (Django serves the shell, SPA owns routing)
http://localhost:8000/admin/	Django admin
http://localhost:8000/api/docs	Live OpenAPI spec for the ninja API (DEBUG only)
http://localhost:3000/	Vite dev server (HMR; usually proxied transparently)
http://localhost:8025/	Mailpit — inspect outgoing emails
http://localhost:9001/	MinIO console — browse the media bucket

Note: Use http://localhost:8000/ rather than http://127.0.0.1:8000/ so passkey enrollment works — WebAuthn rejects bare IP addresses as Relying Party IDs.

Just commands

The Django Base Site comes with Just recipes for all the most common commands and tasks. To see the full list run just in the root of the project. Common ones:

start                        # docker compose up
start_with_debugpy           # Start with debugpy listening on :5678
stop                         # Stop all services
build                        # Rebuild Docker images + collectstatic
build_frontend               # bun run build + collectstatic
clean                        # Remove build files, caches, coverage data
collectstatic                # Run Django's collectstatic
format                       # Format Python (ruff), JS (eslint), HTML (djlint), justfile
lint                         # Run all linters + ty type check + check for missing migrations
test                         # pytest (Django + ninja API tests)
test_with_coverage           # pytest --cov, then open the HTML report
test_e2e [args]              # Build the frontend, then run the Playwright e2e suite
db_dump                      # pg_dump to ~/Downloads
db_restore [dump_file]       # Restore from the latest dump (or a specific file)
upgrade_python_packages      # uv sync --all-packages --all-extras
upgrade_node_packages        # bun update
create_env                   # Generate .env from the schema in pyproject.toml

Deploying to Production

The Django base site is designed to be production ready because it comes with a production ready multi-stage Dockerfile. You can also read a blog post about using it with fly.io. If you want to blog about using the Django Base Site with other PaaS providers, please let me know, and I can link to the post here.

Contribute

1. Look for an open issue or create new issue to get a dialog going about the new feature or bug that you've discovered.
2. Fork the repository on GitHub to start making your changes to the main branch (or branch off of it).
3. Make a pull request.