{% 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

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
   

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_TRACE_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