fuzzy-couscous 1.4.0

Generate a django project from the fuzzy-couscous template.

fuzzy-couscous

My highly opinionated django project template based on django's startproject --template. This project is heavily inspired by cookiecutter-django but is meant to be a lighter version.

Features

• Django 4+
• Python 3.10+
• Frontend: htmx with editor support using web-types
• Template fragment with django-render-block
• Secure production settings, https only.
• Settings using django-environ
• Login / signup via django-allauth
• Custom user model based on django-improved-user
• Login using email instead of username
• Automatically reload your browser in development via django-browser-reload
• Better development experience with django-fastdev
• Amazon SES for production email via Anymail
• Docker ready for production
• Optional production cache settings using the CACHE_URL or REDIS_URL environment variables.
• captain-definition for deploying to caprover
• Sentry for performance/error monitoring
• Serve static files with Whitenoise
• Default integration with pre-commit for identifying simple issues before submission to code review
• Integrated task runner with poethepoet
• Dependency management using poetry

Templates

I use github branches to create variations of the base template.

• main: The base template
• tailwind: The base template + tailwindcss via pytailwindcss
• bootstrap: The base template + bootstrap5 via django-bootstrap5

Usage

Note: fuzzy-couscous is a bit long to type each time, so there is an alias cuzzy that you can use instead.

Since this template uses django's startproject --template, you can easily clone the project on your computer and generate a django project by using the command django-admin and specifying the fuzzy-couscous/project_name folder as the template. The final command is a bit long so I made a simple cli to simplify the process, install it with the command below:

pip install fuzzy-couscous==1.4.0

now initialize a new django project with the command below:

fuzzy-couscous make my_new_project

or

cuzzy make my_new_project

NOTE: You probably want to update the authors key in the pyproject.toml file in the [tool.poetry] section.

This command may take two optional arguments:

--repo (-r): This template makes a lot of assumptions, if you like it but want to make some slight adjustments, make your own couscous by forking this repo. You can then use this option to specify your github repository with the format username/repo.

Example:

fuzzy-couscous make my_new_site --repo "Tobi-De/fuzzy-couscous"

--branch (-b): Specify the branch from which you want to create the template (e.g. tailwind), the default value being main.

Example:

fuzzy-couscous make my_new_site -b tailwind

If you've read this far and still think this template doesn't work for you, feel free to create your own template and copy and paste what you want from other similar projects like I did.

Some examples of templates you can use as inspiration:

• cookiecutter-django
• wemake-django-template
• django-startproject-templates

Additional commands

Some additional commands I added to automate some boring stuff. These commands should be run at the root of your projects, most will work even in projects that have not been generated with this template.

Usage

fuzzy-couscous command

write-env: Running this will create a new .env by filling the file with the keys and values from the following options:

1. a env.template file, used if it exists
2. a DEFAULT_VALUES dictionary, internal to the fuzzy-couscous package, contains some default for common keys, DJANGO_DEBUG, DJANGO_SECRET_KEY, etc.
3. a .env file, used if it exists

Note: The order defines the priority of the values that are used, which means that the values contained in your original .env file are preserved if the file exists.

This command defines two additional optional options:

• --fill-missing (-f): Prompt for missing values before the final .env file is generated
• --output-file (-o): The output filename, default to .env

work: run multiple command in parallel. When working with tailwind, I usually have to run the django runserver command and the tailwind compile command, so I made this to run both in one command. This command use the python subprocess module to run the commands in the same shell. By default it will try to run the two commands below:

• poe r: run the django development server
• poe t: Compile tailwind in watch mode, available if you create your project using the tailwind branch

To specify your own commands, use the -c option, example:

fuzzy-coucsous work -c "python manage.py runserver" -c "python -m http.server 9000"

Tips

This section gathers tips, copy and paste configurations and package recommendations that I use quite often in my projects to solve specific problems.

Settings

If there is a setting in settings.py or elsewhere that you don't understand, go to the official django settings reference page and press Ctrl + F to search for it. I used the django-production package to configure the production settings which I then customized. I have removed the package as a dependency but I advise you to go and check for yourself what is available.

Dynamic web pages

HTMX for simple interactive elements, django-unicorn if I need something more integrated with django. It's not a binary choice, you can use both, the main advantage for me is the simplicity compared to a frontend javascript framework.

Note: If you use htmx boost + debug toolbar (already included in the template), you will need this.

Task queues and schedulers

Task queues are used to offload tasks to a dedicated worker process when the processing of those tasks does not fit into a traditional request-response cycle. Basically, if you need to do something that might take too long to process and whose result does not need to be shown immediately to the user, you use a queue manager. Schedulers are used to periodically run tasks. There are many options available in the django third-party ecosystem, some focus solely on providing a task queue, others are just schedulers and many of them provide both in one package. You can also search for purely python solutions and integrate them into your django project yourself.

I prefer options that do not require additional infrastructure (redis, rabbitmq, etc.) for simple tasks. For more complex tasks, I tend to choose a solution that supports redis as a task broker.

Doesn't require setup of external tools, redis, rabbitmq, etc..

• django-chard: Task queue
• django-pgpubsub: Task queue
• procrastinate: Task queue + scheduler
• django-q2: Task queue + scheduler
• rocketry: Scheduler

Require the setup of external tools, redis, rabbitmq, etc.

• django-dramatiq: Task queue
• django-rq: Task queue + scheduler via django-rq-scheduler
• wakaq: Task queue + scheduler

Note: The order matters, that's the order in which I would choose one of these packages.

Media storage

Media files in django usually refer to files uploaded by users, profile pictures, product images, etc. I usually manage my media files using django-storages. Here is how I set it up.

# core/storages.py
from storages.backends.s3boto3 import S3Boto3Storage

class MediaRootS3Boto3Storage(S3Boto3Storage):
    location = "media"
    file_overwrite = False

    
# settings.py - production settings
AWS_ACCESS_KEY_ID = env("DJANGO_AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = env("DJANGO_AWS_SECRET_ACCESS_KEY")
AWS_STORAGE_BUCKET_NAME = env("DJANGO_AWS_STORAGE_BUCKET_NAME")
DEFAULT_FILE_STORAGE = "project_name.core.storages.MediaRootS3Boto3Storage"
MEDIA_URL = f"https://{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com/media/"

Database backup

Whenever possible, take advantage of a fully managed database solution, they usually offer automatic backup of your databases. In my opinion, this is the best option if you don't want to deal with the hassle of managing your own database.

• Amazon RDS
• Linode Managed Databases
• DigitalOcean Managed Databases
• Heroku postgres

For specific postgresql options, see their hosting support page.

However, if for some reason you want / need to manage your database yourself and just want an automatic backup solution then django-dbbackup is what you need. You can use one of the scheduling packages discussed above to periodically run the backup command.

Health check your django project

Health check is about making sure that your django application and related services are always available / running. My go-to package for this is django-health-check. After installing and configuring django-health-check, you need to associate it with an uptime monitoring service, this is the service that will periodically call your health-check endpoint to make sure everything is fine. Here is a list of available options.

• upptime
• uptime-kuma
• uptimerobot
• glitchtip

Read more on the health check pattern here.

Extra that I haven't tried myself yet

• django-linear-migrations: Read introduction post
• django-read-only: Disable Django database writes.

Documentation

This template does not include a documentation setup, but it is very important for most projects (at least it should be) to have a documentation site, especially if you are not working alone. Here are the options I would suggest for setting up a documentation, recently I tend to favor the first one.

• Mkdocs with the Material theme
• Sphinx with the Furo theme

There is a chance that in the future I will include the docs directly in the template but for now here is a quick guide to configure mkdocs with the material theme:

Installation and configurations

Copy the configuration below into your pyproject.toml file under the [tool.poetry.dependencies] section.

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.4.2"
mkdocs-material = "^8.5.10"
mkdocs-material-extensions = "^1.1.1"
mkdocs-include-markdown-plugin = "^3.9.1"

Install the new dependencies.

poetry install --with docs

Create your new mkdocs site.

mkdocs new .

Update the mkdocs.yml file to specify the material theme, your configuration should look like this:

site_name: My Docs # change this to the name of your project
theme:
  name: material

If you noticed, the dependencies added above via the section [tool.poetry.group.docs.dependencies] include more than just mkdocs and the material theme, specifically :

• mkdocs-material-extensions: Markdown extension resources for MkDocs for Material
• mkdocs-include-markdown-plugin: Include other markdown files in your mkdocs site

For a complete example of how I configure them in projects, see this configuration file.

Deploy your documentation

Mkdocs can turn your documentation into a static site that you can host anywhere, netlify, github pages, etc. To build your site, run the command below and you will have a new site directory at the root of your project:

mkdocs build

This folder contains everything that is necessary to deploy your static site.

If you choose the github pages route, you can automate the process with github actions, the official mkdocs-material documentation explains how to do it. To use github actions, you will probably need a requirements.txt file, you can generate one with only what is needed to build the docs with the command below.

poetry export -f requirements.txt --output docs/requirements.txt --without-hashes --only docs

Read the mkdocs and mkdocs-material docs for more advanced configurations and details on what is possible.

Deployment

This template was configured to simplify deployment on caprover, since that is what I use 99% of the time.

CapRover is an extremely easy to use app/database deployment & web server manager for your NodeJS, Python, PHP, ASP.NET, Ruby, MySQL, MongoDB, Postgres, WordPress (and etc...) applications! Official site

CapRover is a self-hosted PaaS solution, think heroku but on your own servers. Nowadays, I tend to prefer PaaS solutions over manual deployment and configuration, as they are easy to use with little configuration to deploy most apps. Software is usually quite a pain to deploy and even though I've gotten better at it over time, I'll always choose a managed solution over manual deployment. Some other options than CapRover are:

• Dokku (self hosted)
• Fly (hosted)
• Render (hosted)
• Coolify (self hosted)
• DigitalOcean App Platform (hosted)
• AWS Elastic Beanstalk (hosted)
• Btn (hosted and not ready yet)

I find that self-hosted solutions are generally cheaper than managed/hosted solutions, but I don't have much experience with managed solutions, so I could be wrong, do your own research and if you can afford it, try them out to see what works best for you.

After installing CaProver with the getting started guide, there is not much left to do, create a new application and in the section deployment. configure your application using the third method Method 3: Deploy from Github/Bitbucket/Gitlab.

Note: If you use github, instead of entering your password directly into the password field, you can use a personal access token, which is a more secure option.

Tip: Checkout caprover automatic deploy to automate the deployment of your applications.