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, prettier for formatting and linting all code & templates
• goodconf for structured & documented environment variable configuration
• structured logging in deployment and pretty logging in development
• gunicorn and whitenoise for production deployments
• tailwindcss for utility-first CSS
• pytest for testing, pytest-xdist for parallel suport, pytest-socket to block network connections, and coverage
• mypy for type checks
• production-hardened settings

Requirements

• Docker
• uv (recommended)

Usage

Start project

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

Not using uv? Expand for usage with pip

1. Create and activate a virtualenv:

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

2. Install Django with pip install django

3. 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

Quick start

Enter the project directory:

cd YOUR_PROJECT_NAME

Initialize the project & tooling:

make init

Start the Django test server:

make run

Open browser at http://localhost:8000

Contributing

See CONTRIBUTING.md for instructions on how to contribute to and maintain this project.

---

Click to preview the generated project README

{{ project_name }}

Requirements

• Docker

Installation

Build the project:

make init

Usage

Run the project

make run

Open http://localhost:8000/.

Admin access

Create super user:

docker compose run --rm app python manage.py createsuperuser

Access http://localhost:8000/{{ project_name }}-admin/.

Running commands

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 python manage.py createsuperuser
docker compose run --rm app python manage.py migrate
docker compose run --rm app python manage.py shell

Stop containers

To stop containers run:

docker compose down

Update project

To rebuild the project after adding or updating requirements:

docker compose build

Configuration / Environment Variables

These are the environment variables defined in config.py. This documentation is automatically regenerated by precommit when modified.

• 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
• TEMPLATE_DEBUG
  • description: Enable to measure template coverage
  • type: bool
  • default: False

Makefile commands

Available make commands:

init                      Initialize the project
run                       Run the project
test                      Run tests
upgrade-requirements      Upgrade all dependencies in uv.lock