Awesome
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 authenticationdjango-click
for nicer management commandsdjango-email-relay
for sending emails via a central database queuedjango-filter
for filtering querysetsdjango-health-check
for application, database, storage, and other health checksdjango-q2
for a task queue, using the built-in database brokercroniter
for cron tasks
django-simple-history
for tracking historical changes to modelsdjango-storages
for file storage using S3django-template-partials
for easy template partialsenvirons
for configuration via environment variablesheroicons
for easy access to Heroicons in Django templateshttpx
for making HTTP requestsneapolitan
for quick and easy CRUD viewssentry-sdk
for error trackingwhitenoise
for serving static files from Django- Also includes the following packages to make development easier:
django-browser-reload
for getting that HMR feeling in Djangodjango-debug-toolbar
, 'nuff saiddjango-extensions
for various management commands, but let's be honest -- it's mainly forshell_plus
coverage
anddjango-coverage-plugin
for test coverageipython
for a better shellmodel_bakery
for easy model creation in testsmypy
anddjango-stubs
for static type checkingpytest
for testingpytest-django
for Django pytest helperspytest-is-running
, what it says on the tinpytest-randomly
andpytest-reverse
for keeping tests honestpytest-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 thefuro
theme - Automatic linting and formatting via
pre-commit
blacken-docs
becauseruff
doesn'tdjango-upgrade
for keeping Django up to date automaticallydjlint
for linting and formatting Django templatesruff
for blazingly fast formatting and lintingprettier
for formatting CSS, JavaScript, TypeScript, and YAMLrustywind
for sorting Tailwind CSS classes automaticallyvalidate-pyproject
for ensuring thatpyproject.toml
is validpretty-format-toml
vialanguage-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 adocker-compose.prod.yml
to simulate production
- A multi-stage
just
for running common development tasks- Deployment to Fly.io with a
fly.toml
file, withdjango-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
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 usescopier-template-extensions
to simplify some of the Jinja templating. You cannot use this template without trusting it. Please review the files within theextensions
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:
-
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. -
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.
-
Regenerate your
requirements.txt
file (usually, this will mean runningjust py lock
) -
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
- Re-run your setup script to confirm everything still works in your package. (Usually, this will be
-
Commit your changes and open a pull request.
- Make sure CI tests pass
- Make sure other CI processes pass
-
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.