README.md

django-twc-project

django-twc-project is the project template for all web applications at The Westervelt Company. This template is built on top of the Django web framework and is designed to be a starting point for new web applications. It includes a number of best practices and tools to help you get started quickly.

It is tailored to the needs of The Westervelt Company and is not intended for general use. However, it is open source and available for anyone take inspiration from or use and modify. For the greater good!

Features

This template is built using Copier and includes the following features:

• Django
  • django-allauth for user authentication
  • django-click for nicer management commands
  • django-email-relay for sending emails via a central database queue
  • django-filter for filtering querysets
  • django-health-check for application, database, storage, and other health checks
  • django-q2 for a task queue, using the built-in database broker
    • croniter for cron tasks
  • django-simple-history for tracking historical changes to models
  • django-storages for file storage using S3
  • django-template-partials for easy template partials
  • environs for configuration via environment variables
  • heroicons for easy access to Heroicons in Django templates
  • httpx for making HTTP requests
  • neapolitan for quick and easy CRUD views
  • sentry-sdk for error tracking
  • whitenoise for serving static files from Django
  • Also includes the following packages to make development easier:
    • django-browser-reload for getting that HMR feeling in Django
    • django-debug-toolbar, 'nuff said
    • django-extensions for various management commands, but let's be honest -- it's mainly for shell_plus
    • coverage and django-coverage-plugin for test coverage
    • ipython for a better shell
    • model_bakery for easy model creation in tests
    • mypy and django-stubs for static type checking
    • pytest for testing
      • pytest-django for Django pytest helpers
      • pytest-is-running, what it says on the tin
      • pytest-randomly and pytest-reverse for keeping tests honest
      • pytest-xdist for parallel testing, because ain't nobody got time for a slow test suite
• HTMX with django-htmx
• Alpine.js
• Tailwind CSS with django-tailwind-cli
• (optional) Vite with django-vite
• Dependency management with pip-tools
  • Dependabot for automatic dependency updates
• Documentation built with Sphinx, MyST-Parser, and the furo theme
• Automatic linting and formatting via pre-commit
  • blacken-docs because ruff doesn't
  • django-upgrade for keeping Django up to date automatically
  • djlint for linting and formatting Django templates
  • ruff for blazingly fast formatting and linting
  • prettier for formatting CSS, JavaScript, TypeScript, and YAML
  • rustywind for sorting Tailwind CSS classes automatically
  • validate-pyproject for ensuring that pyproject.toml is valid
  • pretty-format-toml via language-formatters-pre-commit-hooks for TOML formatting
• Docker for local development and deployment
  • A multi-stage Dockerfile to targeting different use cases (application/tailwind/vite/worker in development, full image in production)
    • Tailscale included for easy access to private nodes on Tailnet
  • A docker-compose.yml file for local development, with a docker-compose.prod.yml to simulate production
• just for running common development tasks
• Deployment to Fly.io with a fly.toml file, with django-flyio giving some niceties specific to Fly
• CI/CD with GitHub Actions
  • Testing
  • Type checking
  • Django deployment checks
  • Deploying to Fly.io
    • bumpver for version bumping
    • 1Password and the 1password/load-secrets-action to manage secrets

Usage

To use this template, you will need to install Copier and then run the following command:

copier copy gh:westerveltco/django-twc-project <destination>

Examples

Examples are provided in the examples directory.

Contributing

As this template is mainly for internal use at The Westervelt Company, we do not generally accept contributions from external sources. However, if you have any suggestions or issues, please feel free to open an issue or pull request.

License

django-twc-project is licensed under the MIT License. See the LICENSE file for more information.