Basic Django Template

Quick Start

This template creates a project that is managed using uv so if you don't already have it installed you should do so.

1. Install copier:

   uv tool install copier
   

2. Scaffold your project:

   copier copy gh:burnsmcd/cor-django-template /path/to/new/project
   

The above will create a new directory (/path/to/new/project) with your new Django project.

Be sure to update the README.md file, removing everything above the title "Actual Project Name", update that title, and add the path to the git repo.

What's Included

The generated application only contains the basics needed for most Django projects that render the site using Django's template system.

• HTMX
• Cotton
• Custom user model
• Basic docker compose setup for local testing in containers

It also assumes the database used in the deployment environments will be PostgreSQL.

Custom User Model

A custom user model and custom user manager is included that removes the username and replaces it with email. Much of the code for this was liberated from this article and a bit from this video and this related repo. Basic updates to forms.py and admin.py are also included.

Initial Project Setup

The first time you run through the installation steps you'll need to run git init before you start and then uv run manage.py makemigrations before running uv run manage.py migrate in order to create the initial migration files.

Actual Project Name

Installation

1. Install uv.
2. git clone <path-to-git-repo>
3. cd <path-to-git-repo>
4. uv venv
5. source .venv/bin/activate
6. uv sync
7. uv run pre-commit install
8. cp .env.example .env
9. export DJANGO_SETTINGS_MODULE=core.settings.local
10. uv run manage.py makemigrations
11. uv run manage.py migrate
12. uv run manage.py createsuperuser
13. uv run manage.py collectstatic
14. npm install
15. uv run manage.py dev

Unit Tests

Running uv run pytest will run all of the tests in your Django app named test.py, tests.py, test**.py, and tests**.py (see pyproject.toml for details).

To Use PostgreSQL

1. Install Docker.
2. Edit .env and uncomment the database configuration lines as documented in the file.
3. uv run manage.py start_db

To stop the database server run uv run manage.py stop_db. You can specify the local port the contaner is listening on by using the "--port" option, for example uv run manage.py start_db --port 9876 (make sure to update you .env file with the new port number). This can be helpful if you're working on multiple projects, each with their own PostgreSQL server.

To Use Redis

1. Install Docker.
2. Edit .env and uncomment the database configuration lines as documented in the file.
3. uv run manage.py start_redis

To stop the Redis server run uv run manage.py stop_redis. You can specify the local port the contaner is listening on by using the "--port" option, for example uv run manage.py start_redis --port 9876 (make sure to update you .env file with the new port number). This can be helpful if you're working on multiple projects, each with their own Redis server.

Running Multiple Processes With Honcho

Honcho provides the ability to run multiple processes (e.g. Django server, tailwind cli) as described in a Procfile. There is a custom management command that makes running all of the processes specified in the Procfile convenient - uv run manage.py dev.

Testing With Docker

To test the container before deployment the docker compose file can be used to build and deploy the container locally. There is also a settings file that is used to configure the application for running in the containerized environment.

To build, run, and create the "admin" user in the containerized environment run the following.

1. docker compose -f docker/compose.yml build
2. docker compose -f docker/compose.yml up -d
3. docker compose -f docker/compose.yml exec app /bin/bash
4. source .venv/bin/activate
5. export DJANGO_SETTINGS_MODULE=core.settings.localdocker
6. uv run manage.py createsuperuser