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

Requirements

• Copier
• Copier Template Extensions

Installation

You will need to install the required packages before being able to generate a project using this template. They are automatically included in the development dependencies of the generated project, so this is a one-time by-hand installation.

You can use a tool like pipx or uv tool install for this:

pipx install copier copier-templates-extensions
# or for you bleeding-edge folks
uv tool install copier copier-templates-extensions

Usage

Generating a new package

To use this template, ensure the required packages are installed then run the following command:

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

Note

The --trust flag is used to because this template uses copier-template-extensions to simplify some of the Jinja templating. You cannot use this template without trusting it. Please review the files within the extensions directory to see what is being done.

After running the above command, you will be prompted to fill in some information about your package. Once you have filled in the necessary information, Copier will generate the package for you.

Updating an existing package

To use this template to update a package that already uses django-twc-project to the latest version, make sure Copier is installed.

Make sure the package you're updating is set up properly (run just bootstrap or the equivalent setup command).

💬️ For a detailed walkthrough of updating the directory package, see Josh's comment from July 2024. It goes through many of the problems he ran into and how to resolve them.

In a new branch:

1. Run just copier update-all.

   • You will be prompted to fill in or update some information about your package. Most of the answers will be the same as they were in setup.
   • You may have to upgrade the versions of some packages that were used, such as Tailwind, Playwright, etc.
   • You will need to enter the django-twc-project token

   When update-all is finished running, you may see that pre-commit has linted files.

2. Handle merge conflicts. This is the part of the process that is most unpredictable, as the kinds of conflicts you will encounter will differ from project to project. Some examples include:

   • settings.py: Will most likely need to be updated every time, for every project. Because of how the default secret key is generated in the template, this section of the settings file will probably need to be updated.
   • pyproject.toml or other config files: Your package's configuration may differ from the template for legitimate reasons, and you will need to reconcile what changes to keep and what to discard.
   • requirements.in or other requirements files: You may have some dependency management to do here, if you pin to specific versions for specific reasons or have other changes in your package that need to be kept.

3. Regenerate your requirements.txt file (usually, this will mean running just py lock)

4. Confirm your changes work:

   • Re-run your setup script to confirm everything still works in your package. (Usually, this will be just setup.)
   • Start your app locally and do a basic click-through
   • Run your tests locally

5. Commit your changes and open a pull request.

   • Make sure CI tests pass
   • Make sure other CI processes pass

6. Merge the pull request once CI passes.

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.