Django Starter Project

An opinionated boilerplate for your Django projects.

🎖 Tool Choices

• Env Variables Manager: Django Environ
• Package manager: Poetry
• Database: PostgreSQL
• Task Queue: Celery with Redis
• Testing: PyTest
• Logging: Sentry
• Python Code Formatter: Black
• Static File Storage: AWS S3 or Digital Ocean Spaces
• Dev Orchestration: Docker & Docker Compose
• Static File Compiler: Webpack
• JS lint: ESLint
• Style lint: Stylelint

🤓 Getting started

This is a guide on how to use this repo and save hours of boring configuration.

1) Add the boilerplate

Instead of running django-admin startproject to start your new project, clone this repo in a directory of your choosing

git clone git@github.com:fceruti/django-starter-project.git <new-directory>

At this point you may either

1. Start a clean git repo by removing the .git directory and then running git init.
2. Receive patches and updates of this repo by modifying .git/config and switch [remote "origin"] for [remote "upstream"], and then add your own origin by running git remote add origin <your_repo>.

2) Set environment variables

Following the 12 Factor App Guide, we will configure our app by setting the configuration variables in the environment. To do that, just create a file named .env in the root of the project and django-environ will pick it up and populate our settings.

You may use the example file as a starting point:

cp .env.example .env

3) Create and migrate database

I'll call this database django_db for the purposes of this guide, but you can call it whatever you want. Just watch out for careless copy-pasting.

Now run

poetry run migrate

4) Run the project

You have two choices, either you turn every service on your own or you use docker-compose

A) Use Docker Compose

We need to override DATABASE_URL environment variable inside of the Docker containers to connect directly to your host machine. Create a file called .env.docker with the following content:

DATABASE_URL=postgres://<user>@host.docker.internal:5432/django_db

• user is the user on your host machine that has access to postgres in this case.

Now we are ready to start the project.

docker-compose up

Visit http://127.0.0.1:8000 and you'll see your site up and running 🧘‍♀️

B) Run by yourself

First of all, install pyenv so you can use the specified python version in .python-version file. Then, install poetry, which is a package manager replacement for pip. Now install all the project's dependencies with

poetry install

Make sure you have redis-server running and finally on 3 separate consoles run:

server

poetry run worker

worker

poetry run server

webpack

cd assets
npm install
npm run dev

Visit http://127.0.0.1:8000 and you'll see your site up and running 🧘‍♀️

🧞‍♂️ Shortcuts

Docker commands

Here are a few commands that may come in handy

Command	Description
docker ps	List all containers (-a to include stopped)
docker system df -v	Display a list of all images, containers and volumes
docker logs --follow <container_id>	Display the logs of a container
docker exec -it <container_id> /bin/bash	Attach into a running container
docker run --rm <image_name> /bin/bash	Run a docker container based on an image and get a prompt
docker-compose run --rm web /bin/bash	Same as before but for services defined in docker-compose.yml
docker-compose run --rm web /bin/bash -c 'python manage.py migrate'	Run a management command

Poetry commands

These shortcuts are at your disposal:

Command	Shortcut for
poetry run tests	poetry run pytest tests/
poetry run server	poetry run python manage.py runserver_plus
poetry run worker	poetry run python manage.py celery_autoreload
poetry run shell	poetry run python manage.py shell_plus
poetry run makemigrations	poetry run python manage.py makemigrations
poetry run migrate	poetry run python manage.py migrate

To compile your static files, you need to have npm installed and all the local dependencies (run npm install). Then can execute the following commands

Command	Shortcut for
npm run dev	webpack --mode development --env dev--watch
npm run build_stg	webpack --mode production --env stg
npm run build_prod	webpack --mode production --env prod
npm run lint:js	eslint js/** --fix
npm run lint:csss	stylelint scss/*.scss --syntax scss

🎛 Environment variables

These environment variables can be provided to configure your project.

Django

Name	Values	Default	Description
ENV	dev, test, qa, prod	prod	Indicates in which environment the project is running on
DEBUG	on, off	off	Run server in debug mode
LANGUAGE_CODE	Language Identifier (RFC 3066)	en-US	List of language codes
TIME_ZONE	Record of IANA time zone database	America/Santiago	List of timezones
USE_I18N	on, off	on	Enable translation system
USE_L10N	on, off	on	Enable localized formatting
USE_TZ	on, off	on	Enable timezone aware dates in
DEFAULT_FROM_EMAIL	E-mail address	--	Email address from which transactional emails will be sent from
EMAIL_BACKEND	Path to backend	django.core.mail.backends.smtp.EmailBackend	The backend to use for sending emails. List of backends
SECRET_KEY	Random string	--	Used to provide cryptographic signing
ALLOWED_HOSTS	List of domains	--	Represents the host/domain names that this site can serve.
DJANGO_DATABASE_URL	Database url	--	Describes the database connection with a url structure.
LOGIN_URL	Url	/login/	Url to redirect users when login is needed
LOGIN_REDIRECT_URL	Url	/	Url to redirect users after login in
STATIC_URL	Url	/static/	Url from which static files are served
MEDIA_URL	Url	/media/	Url from which media files are served
STATIC_ROOT	Directory path	${project_root}/static	Directory where all static files will be collected to
MEDIA_ROOT	Directory path	${project_root}/media	Directory where all uploaded files will be stored
LOGS_ROOT	Directory path	${project_root}/logs	Directory where all logs will be stored

Celery

Name	Values	Default	Description
CELERY_BROKER_URL	Database url	--	A common value for development is to use redis://cache, but it's recommended for production to use RabbitMQ
CELERY_TASK_ALWAYS_EAGER	on, off	off	If this is True, all tasks will be executed locally by blocking until the task returns.

Django Storages

Documentation

Name	Values	Default	Description
USE_S3_STATIC_STORAGE	on, off	off	Whether or not to use S3
AWS_ACCESS_KEY_ID	str	--	AWS Access key id
AWS_SECRET_ACCESS_KEY	str	--	AWS Secret access key
AWS_STORAGE_BUCKET_NAME	str	--	Name of S3 bucket to be used

Django Debug Toolbar

Name	Values	Default	Description
USE_DEBUG_TOOLBAR	on, off	off	Enables django debug toolbar

Logging & Sentry

Name	Values	Default	Description
LOGS_ROOT	path	--	Path to the directory where logs are to be stored
USE_SENTRY	on, off	off	Enables sentry
SENTRY_DSN	string	--	Private URL-like configuration

♻️ VSCode settings

Nowadays, my go-to editor is VSCode, so here's a template for .vscode/settings.json:

{
  // Editor
  "editor.formatOnSave": true,

  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true,
    "**/*.egg-info": true
  },

  // Search
  "search.exclude": {
    "**/.git": true,
    "**/.vscode": true,
    "**/node_modules": true,
    "**/static": true,
    "**/media": true,
    "**/logs": true,
    "**/tmp": true,
    "**/locale": true
  },
  "search.showLineNumbers": true,

  // Python
  "python.venvPath": "<env_path>",
  "python.envFile": "${workspaceFolder}/.env",
  "python.jediEnabled": false,

  // Linting
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "python.linting.pylintArgs": [
    "--load-plugins",
    "pylint_django",
    "--rcfile",
    "setup.cfg"
  ],

  // Eslint
  "eslint.options": {
    "configFile": ".eslintrc.json"
  },
  "eslint.nodePath": "assets/node_modules",
  "eslint.workingDirectories": ["assets/"],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },

  // Stylelint
  "css.validate": false,
  "less.validate": false,
  "scss.validate": false
}

To fill the python.venvPath run poetry show -v to see the path to your virtual environment.