django-base-site

📦️ 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.

🧩 Custom Django Applications

These first-party apps under apps/ are the foundation for any B2B SaaS built on this template.

• apps/organizations/ — multi-tenant scaffolding: 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. The accept-invite flow lives in the SPA at /organizations/invite/:key/accept/ and works for anonymous visitors via a sign-in / sign-up roundtrip with ?next=.
• apps/teams/ — generic Team model (organization FK + M2M users) with full CRUD ninja API.
• apps/notifications/ — Notification model (recipient + org + GenericForeignKey target) and NotificationPreference model, ninja API at /api/notifications/ (list, unread-count, bulk, per-row patch/delete, per-user category preferences), a notify() producer service, retention via the purge_expired_notifications celery beat task and the purge_notifications management command, and a bell-dropdown UI with 20-second polling that pauses on hidden tabs. Producers register their models in settings.NOTIFICATIONS_TARGET_MODELS so target deletes cascade-clean their notifications, and declare categories in settings.NOTIFICATIONS_CATEGORIES so users can opt channels in or out per category.

🔧 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.
• Oxlint + Oxfmt (Rust-based, ESLint/Prettier-compatible) - JS/Vue linting and formatting

💄 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, Notifications), org settings (General, Members + Invites, Teams, Billing), notification bell with polling and a /notifications/ archive page, public /pricing/ page, Test Notifications and Impersonate views (superuser/staff).

💳 Billing (opt-in)

Stripe-backed subscriptions tied to Organizations. Off by default — set BILLING_ENABLED=true to turn on.

• apps/billing/ with BillingCustomer, Subscription, and WebhookEvent models. Stripe is the source of truth; we mirror just enough locally to gate features and render the billing UI.
• Settings-declared plan + feature registries (BILLING_PLANS, BILLING_FEATURES) — same pattern as NOTIFICATIONS_CATEGORIES. Plans support monthly/annual prices, free tier, trial periods, per-seat pricing, and a "highlighted" flag for the popular plan.
• Stripe Checkout (full-page redirect) for new subscriptions and Stripe Customer Portal for upgrades, cancels, payment-method updates, and invoice history. Coupons / promotion codes are accepted at Checkout.
• Webhook at /webhooks/stripe/ with HMAC signature verification and WebhookEvent-backed dedupe of Stripe retries.
• Per-seat sync — adding/removing org members updates Stripe quantity via transaction.on_commit in a OrganizationMember post_save/post_delete receiver.
• Trial-ending reminders + drift-recovery reconcile run as celery beat tasks.
• Feature gating: appStore.hasFeature('teams') in the SPA, org_has_feature(org, 'teams') and @requires_feature('teams') in Python. When BILLING_ENABLED=False, every feature falls through to its declared default so the starter template runs without Stripe credentials.
• Local dev: stripe listen --forward-to http://localhost:8000/webhooks/stripe/ to bridge the test-mode webhooks.

📝 Documentation

The Django Base Site uses Zensical (the modern successor to MkDocs + Material for MkDocs, built by the same team) for its documentation.

Documentation source lives in the docs/ directory. Configuration is in zensical.toml at the project root. You can copy the docs when starting a new project if you want to maintain documentation in the same style.

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.

just format and just lint run the formatters and source linters (ruff, djLint, oxfmt, oxlint) natively, so you also need uv (for uvx) and bun (for bunx) on your PATH — uv is already needed for uvx epicenv below. (Only ty and the migration check still run in Docker.)

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 m

a base boilerplate to develop python telegram bots beside the django and celery