{% comment %}

Django Layout

django-layout provides sane defaults for new Django projects based on established best practices and some configuration setups frequently used in Lincoln Loop's projects. It includes:

uv for fast dependency management
ruff for formatting and linting
goodconf for structured & documented environment variable configuration
structured logging in deployment and pretty logging in development
gunicorn and whitenoise for production deployments
production-hardened settings

Usage

With `pip`

create and activate a virtualenv:

 python -m venv --prompt . --upgrade-deps .venv

install Django with pip install django

run the following command (replace YOUR_PROJECT_NAME with your preferred name):

 django-admin startproject \
  --template=https://github.com/lincolnloop/django-layout/zipball/main \
  --extension=py,md,gitignore,yaml,json,toml \
  --name=Makefile,Dockerfile \
  --exclude=.github \
  YOUR_PROJECT_NAME

With `uv`

If you're using uv, you can run the following command (replace YOUR_PROJECT_NAME with your preferred name):

    uv run --with django django-admin startproject \
     --template=https://github.com/lincolnloop/django-layout/zipball/main \
     --extension=py,md,gitignore,yaml,json,toml \
     --name=Makefile,Dockerfile \
     --exclude=.github \
     YOUR_PROJECT_NAME

Development

To update README.md after making changes to the config, run:

find . -type f -name "*.py" -or -name Makefile -or -name README.md | xargs sed -i '' 's/{{ project_name }}/project_name/g'
docker compose run --rm --no-deps app make README.md

Then use git add -p README.md to only commit the changes you want. You can git stash the template changes after your commit.

Note: The text following this comment block will become the README.md of the new project.

{% endcomment %}

{{ project_name }}

Docker Installation

Build and run the project:

docker compose up --build

To run Django commands like migrations and shell or to enter the container bash do:

docker compose run --rm app bash
docker compose run --rm app manage.py createsuperuser
docker compose run --rm app manage.py migrate
docker compose run --rm app manage.py shell

To stop containers run:

docker compose down

To update a container after adding a new requirement for example:

docker compose build

Running the project

Docker

Create super user:

docker compose run --rm app manage.py createsuperuser

Make sure you have the containers running:

docker compose up

Access [localhost:8000/{{ project_name }}-admin/](http://localhost:8000/{{ project_name }}-admin/).

Configuration / Environment Variables

DEBUG
- type: bool
- default: False
ALLOWED_HOSTS
- description: Hosts allowed to serve the site https://docs.djangoproject.com/en/{{ docs_version }}/ref/settings/#allowed-hosts
- type: list[str]
- default: ['*']
DATABASE_URL
- description: A string with the database URL as defined in https://github.com/jazzband/dj-database-url#url-schema
- type: str
- default: sqlite:///./sqlite3.db
DJANGO_ENV
- description: Toggle deployment settings for local development or production
- type: Literal['development', 'dev', 'production']
- default: production
LOG_LEVEL
- description: Python logging level
- type: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
- default: INFO
SECRET_KEY REQUIRED
- description: A long random string you keep secret https://docs.djangoproject.com/en/{{ docs_version }}/ref/settings/#secret-key
- type: str
ENVIRONMENT
- description: Name of deployed environment (e.g. 'staging', 'production')
- type: str
- default: development
BASIC_AUTH_CREDENTIALS
- description: Basic Auth credentials for the site in the format 'username:password'
- type: str
- default: ``
SENTRY_DSN
- description: Sentry DSN to enable error logging
- type: str
- default: ``
SENTRY_TRACES_SAMPLE_RATE
- description: Sentry trace sample rate https://docs.sentry.io/product/sentry-basics/concepts/tracing/trace-view/
- type: float
- default: 0.25

Makefile commands

Available make commands:

README.md                 Update dynamic blocks in README.md
fix                       Fix linting errors
fmt                       Format Python code
lint                      Lint Python code
test                      Run tests
upgrade-requirements      Upgrade all dependencies in uv.lock