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.
🧑💻 Best Practices
- Environs - Used for managing environment variables
- Docker - Docker Compose for development and a multi-stage Dockerfile for production ready Docker image
- UV - Used to maintain python requirements
- Just - Popular tool for running common commands (make equivalent)
📦️ Django Packages
- Django 5 - Latest version of Django
- Celery - Most popular task runner for running asynchronous tasks in the background
- Custom User Model - Custom user model so that the user model can be easily extended
- Django Allauth - The most popular package for adding authentication workflows to a Django project
- Django Crispy Forms - The most popular helper for working with Django forms
- Django Alive - A simple health check package for Django
- Django Maintenance Mode - A simple maintenance mode package for Django
🔧 Python Testing Tools
- Pytest - The most popular Python test runner in the Python community
- Pytest Django - A Django plugin for Pytest
- Pytest-cov - Adds code coverage to tests
- Model Bakery - A faster way to create model instances for tests
- Django Test Plus - Helper functions to write tests faster
🩺 Code Quality, Formatting, and Linting Tools
- Black - Automatic Python code formatting
- Ruff - Extra Python linting and lighting fast because it's written in Rust!
- Mypy - Python Type checking
- dj Lint - Automatic Django HTML template formatting and linting
- Django Debug Toolbar - A toolbar for debugging and optimizing Django queries
- Bandit - Automatic security checking
- Stylelint - Automatic Sass formatting and linting
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
Quickstart Install Script
Copy and past 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.
$ 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]?
To start Docker Compose run:
$ cd /Users/brento/Sites/example
$ just start
$ 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
$ just remove_extra_files
$ find ./public -name ".keep" | xargs rm -rf
$ just start
The Django Base Site comes with Just recipes for all the most common commands and tasks that an engineer will use during
development. To see the full list of commands run
just in the root of the project directory. The following is an
abbreviated list of the most common commands.
build_assets # Build frontend assets
clean # Remove build files, python cache files and test coverage data
collectstatic # Run Django's collectstatic management command
format # Format all code
lint # Lint everything
upgrade_python_requirements # Run pip-compile make the requirement files
open_coverage # Run the django test runner with coverage
start # Start docker-compose
start_with_docs # Start docker-compose with docs
stop # Stop all docker-compose services
test # Run the Django test runner without coverage
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.