Generate a django project from the fuzzy-couscous template.
Project description
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
orREDIS_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 aliascuzzy
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==2.0.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:
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:
- a
env.template
file, used if it exists - a
DEFAULT_VALUES
dictionary, internal to thefuzzy-couscous
package, contains some default for common keys,DJANGO_DEBUG
,DJANGO_SECRET_KEY
, etc. - 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 serverpoe t
: Compile tailwind in watch mode, available if you create your project using thetailwind
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.
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.
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for fuzzy_couscous-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8f0eaa82506da4aac7893994b9ecb803be09d6f59f21c0e06275dd55eb6395ff |
|
MD5 | 62775e69d760273cb16e41c211ed8371 |
|
BLAKE2b-256 | 1af85be097a228add593377d9f8e1c2e8e1a692d2204d9cfc96459f2ed255905 |