Django Base Site

The Django Base Site is an opinionated starter template designed to accelerate new Django projects. Lovingly maintained for over twelve years, it incorporates best practices and essential tools to save days of mundane setup, enabling rapid deployment to production.

✨ Key Features

🧑‍💻 Best Practices:

• Environs: For managing environment variables.
• Docker: Docker Compose for development and a multi-stage Dockerfile for production-ready images.
• UV: Efficiently maintains Python requirements.
• Just: A popular tool for running common commands (similar to Make).
• Logging: Uses python-json-logger and readable-log-formatter for better log parsing.

📦️ Django Packages:

• Django 5: The latest version of the framework.
• Celery: For running asynchronous background tasks.
• Custom User Model: Easily extendable user model.
• Django Allauth: Comprehensive authentication workflows.
• Django Crispy Forms: Helpers for working with Django forms.
• Django Alive: Simple health check package.
• Django Maintenance Mode: For managing site maintenance.

🔧 Python Testing Tools:

• Pytest: The most popular Python test runner.
• Pytest Django: A Django plugin for Pytest.
• Pytest-cov: Adds code coverage to tests.
• Model Bakery: Faster creation of model instances for tests.
• Django Test Plus: Helper functions for writing tests.

🩺 Code Quality, Formatting, and Linting Tools:

• Ruff: Lightning-fast Python formatting and linting (written in Rust).
• Mypy: Python static type checking.
• dj Lint: Automatic Django HTML template formatting and linting.
• Django Debug Toolbar: For debugging and optimizing Django queries.
• Stylelint: Automatic Sass formatting and linting.
• Eslint: Automatic JavaScript formatting and linting.

💄 Frontend:

• Bootstrap 5: A popular UI framework.
• Vite: A fast frontend build tool.

📝 Documentation:

• MkDocs: For project documentation.
• MkDocs Material: A beautiful theme for MkDocs.
• mkdocstrings: Builds documentation from Python docstrings.
• mkdocs-include-markdown-plugin: Includes documentation from other files.
• mkdocs-linkcheck: Automatic link checking.

Installation

Requirements: Ensure Docker and Just are installed.

Quickstart Install Script:

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

This script customizes your project setup. After running, navigate to your project directory and start Docker Compose with 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
$ export SECRET_KEY=$(python -c "import random; print(''.join(random.SystemRandom().choice('abcdefghijklmnopqrstuvwxyz0123456789%^&*(-_=+)') for i in range(50)))")
$ cat > .env <<EOF
DEBUG=on
SECRET_KEY='$SECRET_KEY'
DATABASE_URL=postgres://postgres:@db:5432/postgres
INTERNAL_IPS=127.0.0.1,0.0.0.0
EOF
$ just remove_extra_files
$ find ./public -name ".keep" | xargs rm -rf
$ just start

Usage

The project includes Just recipes for common development tasks. Run just in the root directory for a full list. Common commands include build_assets, clean, collectstatic, format, lint, upgrade_python_requirements, open_coverage, start, start_with_docs, stop, and test.

Deploying to Production

The Django Base Site is production-ready with a multi-stage Dockerfile (config/docker/Dockerfile.web). A blog post details its use with fly.io, and contributions for other PaaS providers are welcome.

Contribute

1. Look for or create an issue.
2. ...