🐍 Django – Top 25 Addons Populaires

Guide IDEO‑Lab des 25 packages les plus utiles pour vos projets Django.

Django REST Framework

Powerful toolkit to build Web APIs.

APIRESTSerializers

1.1

Django Compressor

Powerful toolkit to Compress JS and CSS.

APICompressDevOps

1.2

Django Environ

Manage your Django Settings.

APISettingsDevOps

Django Debug Toolbar

Debug panel for development.

DebugSQLDev

Django Redis

Redis Server Access for Django.

CacheStorageDevOps

Django Allauth

Complete authentication management (local, social).

AuthSocialUsers

Django Crispy Forms

Elegant form rendering.

FormsTemplates

Celery

Async tasks and queue management.

AsyncTasksWorkers

Django Channels

WebSockets and async protocols support.

WebSocketsAsync

Django-filter

QuerySet filtering based on URL queries.

FilterQuerySet

Pillow

Image processing library (ImageField).

ImagesUploads

Django-Taggit

Tag management for any model.

TagsModels

Django-Storages

Storage backends for S3, Azure, GCS, etc.

StorageS3Media

Sentry-SDK

Error monitoring integration.

ErrorsLogging

Django-CORS-Headers

CORS headers management for cross-domain requests.

CORSAPISecurity

Whitenoise

Simplified static files serving in production.

StaticDeploy

Django-Simple-History

Automatic model history tracking.

AuditHistory

Django-Extensions

Management commands and enhanced shell.

manage.pyShell

Django-Import-Export

Import/export data via admin.

AdminData

Django-Guardian

Object-level permissions management.

PermissionsAuth

Django-Two-Factor-Auth

Two-factor authentication integration.

2FASecurity

Django-HTMX

HTMX integration for dynamic pages without heavy JS.

HTMXFrontend

Django-Select2

Select2 widgets integration (autocomplete).

FormsWidgets

Django-Jazzmin

Modern responsive theme for Django admin.

AdminTheme

Django-Waffle

Feature flags management.

FeaturesFlags

Django-Silk

Profiling and inspection of API/SQL requests.

ProfilingDebug

Django-Model-Utils

Useful model fields and mixins.

ModelsUtils

Django-BAT

Track and block failed login attempts.

SecurityLogin

django-environ Settings Env Secrets Deploy

12-factor settings: read config from environment (and optional .env)

django-environ is a small library that makes Django settings cleaner by reading values from environment variables (and optionally a .env file). It helps separate configuration from code, improves deployment portability, and reduces “it works on my machine” problems.

What it solves

Different settings per environment (dev/staging/prod) without branching code.
Typed environment parsing (bool/int/list/url/db).
Centralized config: database, caches, email, debug flags.
Cleaner secrets handling (no secrets committed to git).
Consistent deployments on servers and containers.

Best practice mindset

Env vars override defaults.
.env is for local/dev only.
Production secrets come from the platform (systemd, Docker, CI/CD, vault).
Fail fast if critical vars are missing.

Hard rule

Never commit .env with secrets to version control. Put it in .gitignore.

Install

1) Install package

pip install django-environ

2) No INSTALLED_APPS needed

This is a settings helper. You import it in settings.py.

3) Add .env to gitignore

# .gitignore
                            .env
                            .env.*
                            *.env

Settings pattern

This is a pragmatic baseline for a single-file settings module. For large projects, you can split settings into base.py + dev.py + prod.py while keeping the same env parsing approach.

Minimal baseline (single settings.py)

from pathlib import Path
                    import environ

                    BASE_DIR = Path(__file__).resolve().parent.parent

                    env = environ.Env(
                    DEBUG=(bool, False),
                    SECRET_KEY=(str, ""),
                    ALLOWED_HOSTS=(list, []),
                    )

                    # Optional: load .env in local/dev only
                    # env.read_env(BASE_DIR / ".env")

                    DEBUG = env("DEBUG")
                    SECRET_KEY = env("SECRET_KEY")
                    ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=[])

                    if not SECRET_KEY:
                    raise RuntimeError("SECRET_KEY is missing")

Database parsing (DATABASE_URL)

DATABASES = {
                    "default": env.db("DATABASE_URL", default="sqlite:///db.sqlite3")
                    }

Fail-fast strategy

Critical vars should be required in production. Raise errors early to avoid silent misconfiguration.

Common environment variables

Variable	Purpose	Example
`DJANGO_DEBUG` or `DEBUG`	Enable debug mode (dev only)	`DEBUG=true`
`SECRET_KEY`	Django cryptographic secret	`SECRET_KEY=long-random-string`
`ALLOWED_HOSTS`	Host allowlist	`ALLOWED_HOSTS=example.com,api.example.com`
`DATABASE_URL`	Database DSN	`postgres://user:pass@host:5432/dbname`
`CACHE_URL` (optional)	Cache DSN	`redis://localhost:6379/1`
`CSRF_TRUSTED_ORIGINS`	CSRF trusted origins	`https://example.com,https://*.example.com`
`SECURE_PROXY_SSL_HEADER` (optional)	Reverse proxy SSL header	`HTTP_X_FORWARDED_PROTO,https`

Example .env (development only)

DEBUG=true
                    SECRET_KEY=dev-only-secret
                    ALLOWED_HOSTS=127.0.0.1,localhost
                    DATABASE_URL=sqlite:///db.sqlite3

Secrets & safety

Environment variables are a delivery mechanism, not a security guarantee. The security depends on how you store and inject them (systemd, CI/CD, vault, container secrets).

Risk	Impact	Mitigation
Secrets committed to git	Permanent leak	Never commit .env, use a vault/CI secrets
Secrets in logs	Leak via monitoring	Never print env vars; sanitize debug output
Weak SECRET_KEY	Session/signing compromise	Generate strong random secret; rotate with care
Mis-set DEBUG in production	Information leak	Hard fail if DEBUG is true in prod environment

Production guardrail example

ENVIRONMENT = env("ENVIRONMENT", default="dev")  # dev|staging|prod
                        if ENVIRONMENT == "prod" and DEBUG:
                        raise RuntimeError("DEBUG must be false in production")

Deploy playbook

This is the “do not break prod” sequence. The goal is repeatable deploys with deterministic settings.

Recommended steps

Define environment variables in the platform (systemd/Docker/CI secrets).
Verify required vars exist (SECRET_KEY, DATABASE_URL, ALLOWED_HOSTS).
Run migrations.
Run collectstatic.
Restart the service.
Smoke test critical endpoints.

systemd example (concept)

# /etc/systemd/system/myapp.service (concept)
                    [Service]
                    Environment="ENVIRONMENT=prod"
                    Environment="DEBUG=false"
                    Environment="SECRET_KEY=..."
                    Environment="ALLOWED_HOSTS=example.com"
                    Environment="DATABASE_URL=postgres://user:pass@host:5432/dbname"

Operational tip

Keep a documented “required vars” list. Missing env vars should crash early, not degrade silently.

Troubleshooting

Symptom	Likely cause	Fix
App crashes: SECRET_KEY is missing	Env var not injected	Set SECRET_KEY in platform env, restart service
DEBUG unexpectedly true	.env loaded in production	Do not call `read_env` in prod; guard by ENVIRONMENT
Database connection fails	Bad DATABASE_URL format	Validate DSN; test connectivity; check credentials
Allowed hosts error	ALLOWED_HOSTS not set correctly	Set hostnames; in dev use localhost/127.0.0.1
Different behavior per machine	Hidden local env vars	Normalize with .env in dev; document required vars

Debug tip

Print only non-sensitive “presence checks” (e.g., whether a var exists), never print the secret value.

Links

Official references.

IDEO-Lab notes

• Perfect for multi-app deployments where each service has its own DB/cache/secrets.

• Use ENVIRONMENT=prod + guardrails to prevent accidental DEBUG/unsafe settings.

• Treat .env as developer convenience only.

django-redis Cache Redis Performance Sessions

High-performance Redis cache backend for Django

django-redis connects Django’s cache framework to Redis. It gives you fast in-memory caching, session storage, distributed locks, and a central cache shared across workers. It is a critical building block for scaling read-heavy applications.

Why use Redis cache

Very fast memory-based reads.
Shared cache across multiple app instances.
Reduces DB load dramatically.
Supports TTL, atomic ops, locks.
Useful for rate limits, computed dashboards, API caching.

Typical uses

Page or fragment caching.
Query result caching.
Session backend.
Celery broker / result backend.
Feature flags & runtime config.

Important reminder

Redis is a cache by default. Data may disappear if memory is full or policy evicts keys. Do not store critical permanent data in cache.

Install

1) Install package

pip install django-redis

2) Ensure Redis server is running

redis-server --version

3) Quick connectivity test

redis-cli ping
                            # should return: PONG

Cache configuration

Replace Django default cache with Redis backend. This is the most common baseline.

CACHES = {
                    "default": {
                    "BACKEND": "django_redis.cache.RedisCache",
                    "LOCATION": "redis://127.0.0.1:6379/1",
                    "OPTIONS": {
                    "CLIENT_CLASS": "django_redis.client.DefaultClient",
                    },
                    "TIMEOUT": 300,
                    }
                    }

Recommended options

Use separate DB indexes for cache vs sessions.
Set a default TIMEOUT to prevent unbounded growth.
Enable compression if values are large.

Environment-based config (recommended)

REDIS_URL = env("REDIS_URL", default="redis://127.0.0.1:6379/1")

                    CACHES["default"]["LOCATION"] = REDIS_URL

Usage patterns

Basic cache API

from django.core.cache import cache

                    cache.set("dashboard:stats", {"users": 120}, timeout=300)
                    data = cache.get("dashboard:stats")
                    cache.delete("dashboard:stats")

Pattern	Why it works	Example
Cache expensive query	Avoid repeated DB hits	Dashboard aggregates / analytics
Template fragment cache	Faster rendering	Menus, widgets, summary cards
Per-user cache	Personalized speedups	User profile summaries
Soft TTL pattern	Prevent cache stampede	Refresh in background before expiry

Common anti-pattern

Caching everything blindly causes stale data and memory pressure. Cache only expensive or frequently accessed data.

Sessions & async ecosystem

Use Redis for sessions

SESSION_ENGINE = "django.contrib.sessions.backends.cache"
                    SESSION_CACHE_ALIAS = "default"

Redis ecosystem synergy

Celery broker and result backend.
Rate limiting (DRF throttling backends).
Distributed locks for cron jobs.
Feature flags and runtime toggles.

Ops & performance strategy

Concern	Symptom	Mitigation
Memory exhaustion	Evictions increase	Set maxmemory policy and monitor usage
Hot keys	CPU spikes	Spread keys, avoid huge single objects
Network latency	Slow cache calls	Keep Redis close to app servers
Cache stampede	Many recomputations	Use locks or soft TTL strategy

Useful monitoring commands

redis-cli info memory
                    redis-cli info stats
                    redis-cli monitor

Production rule

Separate Redis instances or DB indexes for cache, sessions, and Celery workloads when traffic grows.

Troubleshooting

Symptom	Likely cause	Fix
Connection refused	Redis not running or wrong host	Check service and connection URL
Cache never hits	Keys expire too quickly	Increase TIMEOUT or inspect key logic
Random session logout	Eviction policy removes sessions	Use dedicated DB or persistence settings
High memory usage	Large cached objects	Compress data or cache smaller payloads
Slow responses despite cache	Network latency or serialization overhead	Co-locate Redis and optimize object size

Debug tip

Use cache.get_or_set() for expensive computations to reduce race conditions and simplify cache logic.

Links

Official references.

IDEO-Lab notes

• Essential for dashboards, analytics widgets and heavy read endpoints.

• Pair with Celery and cache invalidation strategy early.

• Monitor memory and eviction policy from day one.

Django-Compressor Assets Minify Bundle Cache

Bundle and minify CSS/JS in Django templates

django-compressor compresses and bundles CSS/JS referenced in your templates. It can: concatenate assets, minify output, generate hashed filenames, and cache results. This improves load time and reduces the number of requests in production.

Why it matters

Reduces HTTP requests by bundling assets.
Minifies CSS/JS for smaller payloads.
Supports caching to avoid recomputing bundles.
Works at template level (easy incremental adoption).
Helps when you keep a “Django template + vanilla JS” stack.

When to avoid

If you already use Webpack/Vite/ESBuild pipeline fully.
If your JS is mostly module-bundled externally.
If you cannot run build steps on deploy (unless offline compression is used).

Key constraint

Compression can require external tools (minifiers). Plan your production pipeline accordingly, or use offline compression during deployment.

Install

1) Install package

pip install django-compressor

2) Add apps

INSTALLED_APPS += ["compressor"]

3) Staticfiles finder

Compressor needs a finder to locate files referenced in templates.

STATICFILES_FINDERS = [
                            "django.contrib.staticfiles.finders.FileSystemFinder",
                            "django.contrib.staticfiles.finders.AppDirectoriesFinder",
                            "compressor.finders.CompressorFinder",
                            ]

Quick validation

Enable compressor in settings (next tab).
Add one compress block in a template.
Load the page and verify bundled output is served.

Configuration

Start with a clean baseline: enable compressor, choose output directory, and configure caching.

Baseline settings

COMPRESS_ENABLED = True
                    COMPRESS_URL = STATIC_URL
                    COMPRESS_ROOT = STATIC_ROOT
                    COMPRESS_OUTPUT_DIR = "CACHE"
                    COMPRESS_OFFLINE = False

Caching recommendation

If you have Redis/Memcached, use it. Compression is an expensive operation; caching avoids recomputation.

Minifier backends (concept)

Asset	How minification happens	Notes
CSS	Filter pipeline / external tool	Verify your chosen filter is installed
JS	Filter pipeline / external tool	Be careful with modern syntax if tools are old
SCSS/LESS (optional)	Preprocessing filters	Usually handled by Vite/Webpack instead

Usage

Wrap your CSS/JS blocks with the compress template tag. Use templatetag here to display snippets without executing them.

Template example (CSS)

{% load compress %}
                    {% compress css %}
                    <link rel="stylesheet" href="{% static 'css/app.css' %}">
                    <link rel="stylesheet" href="{% static 'css/theme.css' %}">
                    {% endcompress %}

Template example (JS)

{% load compress %}
                    {% compress js %}
                    <script src="{% static 'js/app.js' %}"></script>
                    <script src="{% static 'js/charts.js' %}"></script>
                    {% endcompress %}

Common mistake

If you place template tags inside a <pre> without escaping, Django will try to execute them and your page may crash if the library is not installed.

Pipeline choices

Approach	Best for	Tradeoffs
Compressor only	Django template projects, simple assets	Minifiers may be limited vs modern JS bundlers
Vite/Webpack only	Modern SPA or heavy JS	More build complexity, but best output
Hybrid	Mostly Django + some bundles	Requires discipline to avoid double-processing

IDEO-Lab pragmatic take

If your UI is “vanilla JS + templates”, compressor is a clean win. If you have complex JS apps, keep the bundling in Vite/Webpack and use compressor only for legacy/static blocks.

Production strategy

Production stability depends on how you run compression: on-the-fly or offline. Offline compression is usually safer because it turns bundling into a deploy step.

Mode	Behavior	Recommendation
On-the-fly	Compress at runtime	OK for staging; can add latency in production
Offline	Compress during deploy	Preferred for production: predictable and fast

Offline compression command

python manage.py compress

Production must-have

Ensure your deploy pipeline runs: collectstatic then (optionally) compress. If you skip these steps, assets may be missing or uncompressed.

Troubleshooting

Symptom	Likely cause	Fix
Template tag not found	Library not installed / app missing	Install `django-compressor`, add `compressor` to INSTALLED_APPS
Output files not served	Static settings mismatch	Verify STATIC_ROOT/STATIC_URL and `collectstatic`
Files not found during compress	Missing finder or wrong paths	Add `CompressorFinder` and fix static paths
Minification errors	External tool missing or incompatible	Adjust filters or use offline mode with proper tools

Debug tip

Start on staging with COMPRESS_ENABLED and verify output is generated. Then move to offline mode for production deployments.

Links

Official references.

IDEO-Lab notes

• Use it for template-based pages and keep modern JS bundles in a dedicated toolchain.

• Prefer offline compression for production consistency.

• Verify static finders and deployment steps (collectstatic + compress).

DJANGO REST FRAMEWORK v3.15

Le Standard Industriel des API Django

Django REST Framework (DRF) est une boîte à outils puissante et flexible pour construire des API Web. Il est conçu pour simplifier la sérialisation des données et gérer les complexités du protocole HTTP (négociation de contenu, authentification, permissions).

Historique & Impact

Créé par Tom Christie (Encode.io), DRF a débuté en 2011. Devant le manque de solutions robustes, le projet a pris son envol grâce à une campagne Kickstarter célèbre pour la version 3, prouvant que les développeurs étaient prêts à payer pour des outils Open Source de qualité.

Aujourd'hui, c'est le package Django le plus utilisé après le framework lui-même.

La "Killer Feature" : Browsable API

Contrairement à d'autres frameworks qui ne renvoient que du JSON brut, DRF génère automatiquement une interface Web HTML navigable pour chaque endpoint. Cela permet aux développeurs de tester, debugger et explorer l'API directement dans le navigateur sans outils tiers comme Postman.

28k+

GitHub Stars

Utilisé par :

Mozilla
Red Hat
Heroku
Eventbrite

Installation & Configuration Avancée

Matrice de Compatibilité

DRF Version	Django	Python	Statut
3.15+	4.2, 5.0+	3.8 - 3.12	Actuel
3.14	3.2, 4.0, 4.1	3.6 - 3.10	Stable

1. Installation des paquets

TERMINAL / BASH

                        pip install djangorestframework
                        pip install markdown       # Indispensable pour la Browsable API
                        pip install django-filter  # Requis pour les filtres (?price__gt=100)

2. settings.py (Configuration Pro)

Voici une configuration recommandée pour un projet en production.

settings.py

                        INSTALLED_APPS = [
                        ...
                        'rest_framework',
                        'django_filters',
                        ]

                        REST_FRAMEWORK = {
                        # Sécurité : Par défaut, lecture seule pour anonymes, écriture pour auth
                        'DEFAULT_PERMISSION_CLASSES': [
                        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
                        ],
                        # Auth : Session (Web) et Token (Apps/Scripts)
                        'DEFAULT_AUTHENTICATION_CLASSES': [
                        'rest_framework.authentication.SessionAuthentication',
                        'rest_framework.authentication.TokenAuthentication',
                        ],
                        # Pagination : Obligatoire pour éviter de tuer la DB
                        'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
                        'PAGE_SIZE': 20,

                        # Format date/heure ISO 8601
                        'DATETIME_FORMAT': '%Y-%m-%dT%H:%M:%S%z',
                        }

Architecture : La Trinité DRF

Contrairement à Django classique (MVT), DRF repose sur trois piliers distincts.

1. Serializers

Le rôle : Traducteur.

Django manipule des objets Python complexes (QuerySets). Le web parle JSON. Le Serializer fait la conversion dans les deux sens.

Valide les données entrantes (POST).
Gère les relations (ForeignKeys).
Similaire aux Forms Django.

2. ViewSets

Le rôle : Contrôleur.

Au lieu d'écrire une vue pour la liste et une vue pour le détail, un ViewSet regroupe toute la logique CRUD.

ModelViewSet : Fournit list, create, retrieve, update, destroy.
ReadOnlyModelViewSet : Lecture seule.

3. Routers

Le rôle : Cartographe.

Fini les regex complexes dans urls.py. Le Router prend un ViewSet et génère automatiquement toutes les URLs standard.

Gère /api/users/ (GET, POST)
Gère /api/users/1/ (GET, PUT, DELETE)

Implémentation CRUD Complète

Création d'une API de gestion de produits. Copiez ces 3 fichiers et vous avez une API fonctionnelle.

1. serializers.py

                        from rest_framework import serializers
                        from .models import Product, Category

                        class ProductSerializer(serializers.ModelSerializer):
                        # Champ calculé (ne vient pas de la DB)
                        discount_price = serializers.SerializerMethodField()
                        # Lien hypertexte vers le détail de la catégorie
                        category = serializers.HyperlinkedRelatedField(
                        view_name='category-detail', read_only=True
                        )

                        class Meta:
                        model = Product
                        fields = ['id', 'name', 'price', 'discount_price', 'category']
                        read_only_fields = ['created_at']

                        def get_discount_price(self, obj):
                        # Logique métier simple
                        return obj.price * 0.9 if obj.on_sale else None

2. views.py

                        from rest_framework import viewsets, filters
                        from rest_framework.permissions import IsAuthenticatedOrReadOnly
                        from django_filters.rest_framework import DjangoFilterBackend
                        from .models import Product
                        from .serializers import ProductSerializer

                        class ProductViewSet(viewsets.ModelViewSet):
                        queryset = Product.objects.all().order_by('-created_at')
                        serializer_class = ProductSerializer

                        # Configuration Permissions
                        permission_classes = [IsAuthenticatedOrReadOnly]

                        # Configuration Filtres et Recherche
                        filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
                        filterset_fields = ['category', 'on_sale']  # ?category=1
                        search_fields = ['name', 'description']      # ?search=iphone
                        ordering_fields = ['price', 'created_at']    # ?ordering=-price

3. urls.py

                        from django.urls import path, include
                        from rest_framework.routers import DefaultRouter
                        from .views import ProductViewSet

                        # Création du routeur
                        router = DefaultRouter()
                        router.register(r'products', ProductViewSet)

                        urlpatterns = [
                        path('api/v1/', include(router.urls)),
                        # Routes pour l'auth browsable API (login/logout)
                        path('api-auth/', include('rest_framework.urls')),
                        ]

Sécurité & Authentification

DRF offre plusieurs mécanismes pour sécuriser votre API.

Méthodes d'Auth

1. Session Authentication

Utilise le système de session de Django (cookies). Parfait pour les appels AJAX depuis le même domaine ou pour l'interface d'admin. C'est le défaut.

2. Token Authentication

Génère un token permanent stocké en base de données. Idéal pour des clients simples (scripts python, apps mobiles basiques).
Header: Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

3. JWT (JSON Web Token)

Le standard moderne (via simplejwt). Stateless, expire, refresh token. Indispensable pour React/Vue/Angular.

Throttling (Limitation)

Pour éviter les attaques DDoS ou le scraping abusif, configurez des limites de débit.

                                REST_FRAMEWORK = {
                                'DEFAULT_THROTTLE_CLASSES': [
                                'rest_framework.throttling.AnonRateThrottle',
                                'rest_framework.throttling.UserRateThrottle'
                                ],
                                'DEFAULT_THROTTLE_RATES': {
                                'anon': '100/day',  # Max 100 req/jour si anonyme
                                'user': '1000/day'  # Max 1000 req/jour si connecté
                                }
                                }

Écosystème & Extensions

DRF est la base, mais ces packages sont quasi-obligatoires en production.

drf-spectacular

Génération automatique de documentation OpenAPI 3.0 (Swagger UI / Redoc). Indispensable pour documenter votre API pour les front-ends.

SimpleJWT

La librairie standard pour gérer l'authentification JWT (access token + refresh token) avec DRF.

django-cors-headers

Ce n'est pas du DRF pur, mais si votre React est sur `localhost:3000` et Django sur `8000`, vous en aurez besoin pour autoriser les requêtes Cross-Origin.

Djoser

Fournit des endpoints REST prêts à l'emploi pour : Login, Register, Reset Password, Activation Email.

Documentation Officielle

Django Debug Toolbar Dev

Le “radar” des problèmes Django en dev

Django Debug Toolbar ajoute une barre latérale dans tes pages Django (mode dev) pour inspecter instantanément les requêtes SQL, les templates rendus, le cache, les signaux, les headers, le timing, etc.

🎯 Pourquoi c’est utile

Identifier les N+1 queries et les pages “lentes” en 2 clics.
Comprendre quelle vue et quels templates ont été utilisés.
Voir les hits/miss du cache et les headers HTTP.
Accélérer les audits perf : timings, count SQL, duplication, etc.

Cas d’usage typiques

N+1

Détection ORM

SQL

Analyse requêtes

TPL

Templates rendus

TIME

Profiling page

Pré-requis

À activer uniquement en développement.
Peut ralentir les pages (logique : il instrumente beaucoup de choses).
À verrouiller côté réseau (allowed hosts / internal IPs) si besoin.

Installation & Configuration

1) Installer

pip install django-debug-toolbar

2) settings.py

INSTALLED_APPS += ["debug_toolbar"]

                            MIDDLEWARE = [
                            "debug_toolbar.middleware.DebugToolbarMiddleware",
                            *MIDDLEWARE,
                            ]

                            INTERNAL_IPS = ["127.0.0.1"]  # ou IP LAN (Docker etc.)

Astuce Docker : ajoute l’IP du host/bridge dans INTERNAL_IPS ou utilise un helper.

3) urls.py

from django.conf import settings
                            from django.urls import include, path

                            urlpatterns = [
                            # ... tes urls ...
                            ]

                            if settings.DEBUG:
                            import debug_toolbar
                            urlpatterns = [path("__debug__/", include(debug_toolbar.urls))] + urlpatterns

Configuration utile

DEBUG_TOOLBAR_CONFIG = {
                    "SHOW_TOOLBAR_CALLBACK": "debug_toolbar.middleware.show_toolbar",
                    }

Activer / désactiver proprement

Garde le package en dépendance dev : requirements-dev.txt
Conditionne l’activation au flag env : DEBUG=True
Ne l’active jamais sur staging/prod (ou alors derrière VPN strict)

Panels : ce que tu vois (et comment l’exploiter)

Panel	Ce qu’il donne	À surveiller
SQL	liste des requêtes + durée + stack trace	N+1, duplication, requêtes sans index, requêtes “longues”
Templates	templates rendus + context keys	includes multiples, templates lourds
Cache	hits/miss + backend	mauvais cache key, cache non utilisé
Signals	signaux déclenchés	signaux trop bavards / chaines d’effets
Headers	req/resp headers	cache-control, cookies, sécurité
Timer	profiling global page	latence view/DB/templates

Limiter les panels (perf)

DEBUG_TOOLBAR_PANELS = [
                    "debug_toolbar.panels.sql.SQLPanel",
                    "debug_toolbar.panels.templates.TemplatesPanel",
                    "debug_toolbar.panels.cache.CachePanel",
                    # ... ajoute au besoin
                    ]

Usage “pro” : diagnostiquer vite

🧠 Routine d’analyse (5 minutes)

Ouvre la page → regarde Timer + nombre de requêtes SQL.
Dans SQL → trie par durée, détecte les requêtes répétées.
Si répétition → corrige via select_related/prefetch_related / agrégations.
Vérifie Templates → repère un include coûteux / boucle lourde.
Regarde Cache → valide que les zones “chaudes” tapent le cache.

Exemple anti N+1 (ORM)

# Avant (N+1)
                    orders = Order.objects.all()
                    for o in orders:
                    print(o.customer.name)

                    # Après (1 requête + join)
                    orders = Order.objects.select_related("customer").all()

Debug Toolbar + DRF ?

Oui : très utile sur endpoints HTML / pages admin / views server-side.
Sur API JSON pure : le rendu toolbar dépend du client (mais le profiling côté serveur reste utile).
Pour API : combine avec logging SQL, APM, ou un middleware de timing.

Sécurité & Bonnes pratiques

⚠️ Jamais en production

La toolbar peut révéler des infos sensibles (SQL, chemins, settings, headers…). Elle est faite pour le DEV.

Checklist rapide

Conditionner l’activation à DEBUG ou variable d’environnement.
Restreindre l’accès via INTERNAL_IPS.
Éviter de la charger sur des pages très sollicitées (même en dev partagé).
Désactiver certains panels si ça “pollue” (perf / bruit).

Mode dev partagé (team)

def show_toolbar(request):
                    return request.user.is_staff and request.META.get("REMOTE_ADDR") in INTERNAL_IPS

                    DEBUG_TOOLBAR_CONFIG = {"SHOW_TOOLBAR_CALLBACK": "config.debug.show_toolbar"}

Écosystème & compléments

Compléments utiles

Django Silk : profiling plus “APM-like” en dev.
django-extensions : outils dev (shell_plus, runscript).
django-querycount : alerte N+1 / seuil SQL.
APM (Sentry/Datadog/NewRelic) : vision prod (mais autre sujet).

SQL

Focal point

La valeur n°1 : comprendre et réduire les requêtes (N+1, duplication, timings).

Utilisé pour :

Audits perf
Chasse N+1
Debug templates
Validation cache

Django-Storages Storage S3 Media

Stockage “cloud-ready” (sans réécrire ton code fichiers)

Django-Storages fournit des backends de stockage pour brancher Django sur des fournisseurs (S3 / GCS / Azure Blob…) via l’API de stockage, tout en gardant la même interface côté app : upload, lecture, gestion des URLs, stockage statique et media, etc.

✅ Ce que ça résout (très concrètement)

Scale : objets dans un bucket, pas sur le disque de ton serveur.
HA : stockage durable (replication / zone / région selon provider).
CDN-friendly : URLs publiques ou signées, cache, distribution.
Dev/Prod : local en dev, cloud en prod (switch propre).
Separation : static vs media, ou buckets distincts.

🎯 Use cases IDEO-Lab

Uploads “toolbox” (whl, pdf, assets).
Images portfolio / CV / bannières.
Exports (JSON, reports, logs).
Backups applicatifs (objets).
Multi-sites sur un même socle.

🧠 Modèle mental (important)

Storage backend = une implémentation de l’interface Django (save/open/url/delete...).

Static files = fichiers “build” (css/js/img) souvent collectés en une fois.

Media files = fichiers utilisateurs (uploads) tout au long de la vie du site.

URL strategy = publique (CDN) vs signée (private) selon sensibilité.

Architecture typique

Browser/User
                        |
                        |  upload/read
                        v
                        Django (Storage API)
                        |
                        |  backend driver (S3/GCS/Azure)
                        v
                        Object Storage Bucket  <----->  CDN (optional)
                        |
                        |  lifecycle / versioning / retention
                        v
                        Durable Storage

Checklist de décision (rapidement)

Public vs Private

Public : images publiques, assets “marketing”.
Private : documents, exports, logs, pièces sensibles.
Private + signed URLs : pattern “clean” (accès contrôlé).

Static vs Media

Static : collectstatic + cache agressif.
Media : accès direct, permissions, quotas.
Souvent 2 buckets + 2 domaines/CDN.

Installation & configuration (base)

1) Installer

pip install django-storages

2) settings.py

INSTALLED_APPS += ["storages"]

3) Principe : un backend pour MEDIA / un backend pour STATIC

STORAGES = {
                            "default": {"BACKEND": "path.to.MediaStorage"},
                            "staticfiles": {"BACKEND": "path.to.StaticStorage"},
                            }

⚠️ Erreurs classiques

Mettre les clés provider directement dans le code (mauvaise idée) → utilise env vars / IAM / Workload Identity.
Confondre STATIC et MEDIA.
Oublier CORS (uploads depuis navigateur) ou headers cache.
Donner un bucket public “par facilité” alors que le contenu est sensible.

Organisation recommandée (sane defaults)

Bucket 1 : static (cache long, versionné, CDN)

Bucket 2 : media (permissions, signed URLs, lifecycle)

Prefix : project/env (ex: ideolab/prod/, ideolab/dev/)

AWS S3 (boto3) : setup propre + options utiles

Installer dépendances S3

pip install boto3

Django-Storages s’appuie sur boto3. Sur EC2, la meilleure pratique est de passer par un IAM Role attaché à l’instance (pas de credentials locaux).

Backends S3

from storages.backends.s3 import S3Storage

Tu peux définir deux classes Storage (static/media) avec des paramètres différents (bucket, prefix, ACL, cache).

Example: MediaStorage / StaticStorage (S3)

# storages_backends.py
                    from storages.backends.s3 import S3Storage

                    class MediaStorage(S3Storage):
                    bucket_name = "myapp-media"
                    location = "media"
                    default_acl = None
                    file_overwrite = False

                    class StaticStorage(S3Storage):
                    bucket_name = "myapp-static"
                    location = "static"
                    default_acl = None
                    file_overwrite = True

STORAGES + URLs (Django)

STORAGES = {
                    "default": {"BACKEND": "project.storages_backends.MediaStorage"},
                    "staticfiles": {"BACKEND": "project.storages_backends.StaticStorage"},
                    }

                    MEDIA_URL = "/media/"
                    STATIC_URL = "/static/"

Headers & cache (vraiment important)

Static : cache long (immutable) + versionnement (hash) recommandé.

Media : cache selon contenu ; attention aux fichiers remplacés.

Si CDN : configure les headers au niveau bucket/CDN pour éviter des assets “plats”.

S3: tableau “option → impact”

Option	Impact	À utiliser quand
`file_overwrite`	Empêche d’écraser un fichier existant (crée un nom unique si collision).	Uploads utilisateurs / versioning
`location`	Prefix dans le bucket (ex: `media/`, `static/`).	Organisation multi-projets
`default_acl = None`	Évite des ACL legacy ; privilégie bucket policy/IAM.	Bonne pratique moderne
`querystring_auth`	URLs signées (temporaire) pour objets privés.	Docs sensibles, downloads contrôlés

⚠️ “Private media” : pattern recommandé

1) Bucket privé + policy stricte

2) Génération d’URL signées côté serveur

3) Expiration courte (ex: 60s–300s)

4) Logs + audit (qui télécharge quoi)

Google Cloud Storage (GCS) : simple, propre, scalable

Idée clé

GCS fonctionne très bien pour du static/media. En prod, vise Workload Identity (ou service account) plutôt que des clés posées sur disque. Ajoute Cloud CDN si tu veux des perfs “web app” très stables.

Example: Storage classes (GCS)

# storages_backends.py
                    from storages.backends.gcloud import GoogleCloudStorage

                    class MediaStorage(GoogleCloudStorage):
                    bucket_name = "myapp-media"
                    location = "media"
                    file_overwrite = False

                    class StaticStorage(GoogleCloudStorage):
                    bucket_name = "myapp-static"
                    location = "static"
                    file_overwrite = True

Typical settings

STORAGES = {
                    "default": {"BACKEND": "project.storages_backends.MediaStorage"},
                    "staticfiles": {"BACKEND": "project.storages_backends.StaticStorage"},
                    }

                    GS_BUCKET_NAME = "myapp-media"

GCS: points d’attention

CORS si upload direct depuis le navigateur.
Cache headers si static derrière CDN.
Private media : signed URLs (pattern identique S3).
Lifecycle rules : purge auto (temp files, exports).

Azure Blob Storage : storage enterprise + CDN

Quand Azure devient “le bon choix”

Stack Azure déjà en place (Entra ID, policies, governance).
Besoin de patterns enterprise (RBAC, audit, compliance).
CDN Azure / Front Door pour distribution.

⚠️ Piège fréquent

Les droits d’accès (RBAC / SAS tokens) doivent être pensés dès le début. Évite les containers “public” si tu as des documents sensibles.

Example: Azure storage class

# storages_backends.py
                    from storages.backends.azure_storage import AzureStorage

                    class MediaStorage(AzureStorage):
                    azure_container = "media"
                    expiration_secs = None

                    class StaticStorage(AzureStorage):
                    azure_container = "static"
                    expiration_secs = None

Azure: pattern clean pour private media

1) Container privé

2) Générer des URLs temporaires (SAS) via backend / service

3) Expiration courte + logs d’accès

Patterns solides (prod) : multi-env, multi-buckets, URLs signées

Pattern A — Local dev / Cloud prod

if DEBUG:
                        # Use local filesystem for speed and simplicity
                        STORAGES = {
                        "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
                        "staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
                        }
                        else:
                        # Use cloud storages
                        STORAGES = {
                        "default": {"BACKEND": "project.storages_backends.MediaStorage"},
                        "staticfiles": {"BACKEND": "project.storages_backends.StaticStorage"},
                        }

Pattern B — URLs signées (private downloads)

from django.core.files.storage import default_storage

                        def get_private_download_url(name: str) -> str:
                        # The storage backend may return signed URLs depending on configuration
                        return default_storage.url(name)

Pattern C — Upload direct navigateur (pré-signé)

Pour les gros fichiers, tu peux générer une URL pré-signée côté backend, et uploader directement vers le bucket, sans faire transiter les données par Django. Résultat : serveur allégé, perfs meilleures.

💡 Convention naming (anti-chaos)

Buckets : project-env-static / project-env-media

Prefix : app_name/ + yyyy/mm/ (si tu veux structurer)

Immutable static : nom hashé (build pipeline)

Sécurité & performance : les règles qui évitent les catastrophes

Sécurité (top risques)

Bucket public par défaut → fuite de données.
Credentials statiques sur disque → compromission.
URLs permanentes sur contenu sensible → partage non contrôlé.
Pas d’audit logs → impossible d’investiguer.

Performance (top gains)

CDN devant static → latence très basse.
Cache headers corrects → charge serveur quasi nulle.
Upload direct → serveur Django épargné.
Lifecycles → coûts stables (purge auto).

Table “action → bénéfice” (prod)

Action	Bénéfice	Remarque
Separate buckets (static/media)	Policies et cache adaptés, maintenance plus simple	Recommandé presque toujours
Signed URLs for private media	Accès contrôlé et traçable	Expire rapidement
CDN for static	Time-to-first-byte très bas	Cache long + invalidation
Lifecycle rules	Réduction coûts, nettoyage automatique	Temp/export/log objects
Role-based auth (no local keys)	Évite la fuite de secrets	IAM/Identity-first

Troubleshooting : symptômes → causes → actions

Symptôme	Cause probable	Action
403 Forbidden sur URL media	Bucket privé sans signed URLs / policy trop stricte	Configurer signed URLs ou ajuster policy/IAM
Uploads OK, mais fichiers introuvables	Mauvais prefix (`location`) ou bucket	Vérifier `bucket_name`/`location` + logs
Static not updating after deploy	Cache CDN trop agressif / pas de versionnement	Hash filenames + invalidation CDN
Timeout sur gros upload	Upload via Django (proxy) + limites reverse proxy	Passer en upload direct pré-signé
Coûts qui explosent	Pas de lifecycle + objets temporaires infinis	Lifecycle rules + monitoring + quotas

Checklist debug (rapide)

Le fichier est-il bien dans le bucket ? (console provider)
Le path correspond-il à location + filename ?
La policy autorise-t-elle GET/PUT ?
Les URLs sont-elles publiques ou signées ?
Le CDN cache-t-il trop ? (headers + purge)

Liens & docs utiles

Conseil : garde cette section “officielle” et stable (docs, repo, providers).

Notes d’intégration IDEO-Lab

• Ajoute une card “Storage” sur le dashboard (S3/GCS/Azure) avec KPI (taille bucket, top prefixes).

• Si tu distribues des assets (whl/pdf), pense à “private + signed URL” plutôt que public.

Sentry SDK Errors Logging APM Tracing

Production error monitoring that actually reduces downtime

Sentry collects exceptions, stack traces, breadcrumbs, user context, release info, and (optionally) performance traces. The goal is not “more logs”, but faster diagnosis: what broke, where, for whom, and what changed.

What you get (concrete)

Error grouping: same root cause aggregated.
Context: request, headers, user id/email (if configured), tags.
Breadcrumbs: events timeline before crash.
Releases: correlate spikes with deploys.
Alerts: notify on regressions and new issues.
Tracing (optional): slow endpoints, DB spans, external calls.

IDEO-Lab usage

Track 500s per app/module (toolbox, dashboards, parsers).
Pinpoint template/runtime errors in production.
Detect spikes after migrations or deploy changes.
Measure API latency (Django + DB spans).
Link errors to release version and git sha.

Signal path

Django exception / log error
                        -> Sentry SDK captures
                        -> Event envelope (context, tags, release)
                        -> Sentry project
                        -> Grouping + Alerts + Dashboards

Golden rules

Keep DSN in env vars, never in code.
Tag everything: env, app, host, release.
Sample traces, but do not sample errors blindly.
Scrub PII (tokens, passwords, cookies).
Ship source maps for JS if you have front assets.

Install

1) Python package

pip install sentry-sdk

2) Minimal DSN

export SENTRY_DSN="https://public_key@o0.ingest.sentry.io/0"

Use environment variables (systemd, docker, CI secrets). Rotate if leaked.

Common install mistakes

SDK installed but not initialized (no events).
DSN missing in production environment.
Network egress blocked (firewall) to Sentry ingest.
PII sent unintentionally (cookies, auth headers).

Core configuration

Recommended init (baseline)

import os
                    import sentry_sdk
                    from sentry_sdk.integrations.django import DjangoIntegration

                    SENTRY_DSN = os.environ.get("SENTRY_DSN", "")

                    if SENTRY_DSN:
                    sentry_sdk.init(
                    dsn=SENTRY_DSN,
                    integrations=[DjangoIntegration()],
                    environment=os.environ.get("APP_ENV", "prod"),
                    release=os.environ.get("APP_RELEASE", "unknown"),
                    send_default_pii=False,
                    traces_sample_rate=float(os.environ.get("SENTRY_TRACES_SAMPLE_RATE", "0.0")),
                    )

Key options

environment: prod/staging/dev separation.
release: deploy correlation (git sha, version).
send_default_pii: keep false by default.
traces_sample_rate: start low (0.05–0.2) and adjust.

Tagging strategy (high value)

sentry_sdk.set_tag("app", "ideolab")
                            sentry_sdk.set_tag("host", os.environ.get("HOSTNAME", "unknown"))
                            sentry_sdk.set_tag("cluster", os.environ.get("CLUSTER", "default"))

Noise control

Problem	Cause	Fix
Too many events	Expected exceptions, bots, bad endpoints	Filter via `before_send`, ignore specific exceptions, adjust routes
Grouping is messy	Dynamic messages, different stack shapes	Use fingerprints/tags, normalize error messages
Tracing too expensive	High sample rate	Lower `traces_sample_rate` and use sampling rules

Django patterns (prod-grade)

Capture handled exceptions (when you decide)

import sentry_sdk

                    def safe_call():
                    try:
                    risky_operation()
                    except Exception as exc:
                    sentry_sdk.capture_exception(exc)
                    raise

Capture messages with context

import sentry_sdk

                    sentry_sdk.capture_message(
                    "Unexpected state in parser pipeline",
                    level="warning",
                    )

Attach request/user context safely

Prefer tags and non-sensitive identifiers. If you need user info, keep it minimal.

import sentry_sdk

                    def set_actor(user_id: str):
                    sentry_sdk.set_user({"id": user_id})

Integrate with logging

import logging

                    logger = logging.getLogger("app")

                    def run_job():
                    logger.info("job_start", extra={"job": "nightly_parser"})
                    # ...
                    logger.error("job_failed", extra={"job": "nightly_parser"})

Release discipline

Set APP_RELEASE on deploy (git sha or semver).
Use the same value across web + workers.
Tag environment explicitly (prod/staging).

Alerts & operations

High-signal alerts

New issue in production
Error spike (regression)
High rate for a specific endpoint
Slow transactions (p95/p99) if tracing enabled

Triage workflow

Identify release correlation
Check tags (app/module/host)
Read stack + breadcrumbs
Fix or rollback
Mark resolved + add note

Operational checklist

Item	Why	Default
Set environment	Separate prod/staging data	`APP_ENV=prod`
Set release	Deploy correlation	`APP_RELEASE=<git_sha>`
Traces sampling	Cost vs insight	Start at 0.05
PII scrubbing	Compliance and security	On (default) + extra filters
Alert routing	Actionable notifications	Ops channel + email fallback

Security & privacy

Treat error telemetry as sensitive: stack traces can include paths, identifiers, and occasionally data. Keep send_default_pii off unless you have a specific need and a clear policy.

Do not send

Passwords, tokens, API keys
Authorization headers
Full cookies content
Raw request bodies with PII

Good practice

Use tags instead of raw payloads
Scrub headers/cookies
Set retention policy in Sentry
Limit access with SSO/RBAC

Filtering events (before_send)

def before_send(event, hint):
                    # Example: drop known noisy errors by message substring
                    exc = event.get("exception", {})
                    # Keep it simple here; implement your own rules carefully
                    return event

Troubleshooting

Symptom	Likely cause	Fix
No events in Sentry	SDK not initialized or DSN missing	Verify env vars + init path + startup logs
Events from dev mixed with prod	Environment not set	Set `APP_ENV` and enforce it in init
Too many issues	No filtering, bots, expected exceptions	Add ignore rules, rate limit noisy endpoints, use `before_send`
Grouping splits	Dynamic error messages	Normalize messages, use tags, adjust fingerprint if needed
High CPU/latency	Tracing sample too high	Reduce sampling, exclude endpoints, tune integrations

Quick verification (prod)

Confirm DSN is set on web + workers.
Trigger a controlled exception on a protected route.
Check “environment” and “release” tags appear.
Verify outbound network access to ingest endpoint.

Links

Keep this section stable: official docs, SDK references, and integration notes.

IDEO-Lab integration notes

• Add a dedicated tag per tool/app module to route alerts.

• Track parser/cron failures from workers with consistent release + host tags.

• Use low tracing sampling first, then increase only where it helps.

Django-CORS-Headers CORS API Security

Cross-domain requests without breaking security

Django-CORS-Headers adds the right CORS response headers so browsers can call your API from another origin (domain/port/protocol). It solves “blocked by CORS policy” while keeping strict security rules.

When you need it

Frontend on different domain than Django API.
Admin tools calling endpoints from a separate origin.
Local dev: localhost:3000 → API localhost:8000.
Using cookies/session auth across origins.
Using Authorization header (Bearer token) from browser.

Golden rules

Never use CORS_ALLOW_ALL_ORIGINS in production.
Whitelist exact origins (scheme + host + port).
Enable credentials only if required.
Know preflight: OPTIONS must return headers.
Keep allowed headers/methods minimal.

CORS is not a security shield

CORS is a browser enforcement mechanism. It does not protect your API from server-to-server calls. You still need authentication, authorization, rate limiting, CSRF rules, and proper access control.

CORS 101 (quick but accurate)

Origin = scheme + host + port
                        Examples:
                        https://ideolab.io            (443 implied)
                        https://api.ideolab.io        (different host)
                        http://localhost:3000         (different port)
                        http://localhost:8000         (API)

                        Same-origin policy blocks JS calls across origins unless CORS allows it.

Simple vs preflighted requests

Simple request

Browser sends the request directly (GET/POST with simple headers). Server must include:

Access-Control-Allow-Origin

Preflight (OPTIONS)

Browser asks permission first when using:

Non-simple methods (PUT/PATCH/DELETE)
Custom headers (Authorization)
Credentials + constraints

Server must answer OPTIONS with allow headers/methods.

Core response headers (what they do)

Header	Meaning	Common pitfall
`Access-Control-Allow-Origin`	Which origin is allowed to read the response	Using `*` with credentials (not allowed)
`Access-Control-Allow-Credentials`	Allow cookies / auth credentials	Forgetting it when using session cookies
`Access-Control-Allow-Headers`	Which request headers are permitted	Missing `Authorization` causes blocked calls
`Access-Control-Allow-Methods`	Which HTTP methods are permitted	Missing PATCH/DELETE triggers preflight failure
`Access-Control-Expose-Headers`	Which response headers JS can read	Frontend cannot read custom headers without it
`Access-Control-Max-Age`	Cache preflight response	Too low = too many preflights

Install (Django)

1) Install package

pip install django-cors-headers

2) Add to INSTALLED_APPS

INSTALLED_APPS += ["corsheaders"]

3) Middleware order matters

Put CorsMiddleware as high as possible, especially before CommonMiddleware.

MIDDLEWARE = [
                            "corsheaders.middleware.CorsMiddleware",
                            "django.middleware.security.SecurityMiddleware",
                            "django.contrib.sessions.middleware.SessionMiddleware",
                            "django.middleware.common.CommonMiddleware",
                            # ...
                            ]

Configuration (safe defaults)

Whitelist exact origins

CORS_ALLOWED_ORIGINS = [
                    "https://ideolab.io",
                    "https://app.ideolab.io",
                    "http://localhost:3000",
                    ]

Headers & methods (minimal)

CORS_ALLOW_HEADERS = [
                            "accept",
                            "authorization",
                            "content-type",
                            "x-csrftoken",
                            "x-requested-with",
                            ]

If you use Bearer tokens from the browser, authorization must be allowed.

Preflight caching

CORS_PREFLIGHT_MAX_AGE = 86400

Reduces OPTIONS spam; keep reasonable to allow policy changes.

Common patterns (choose one)

Pattern	Best for	Key settings
Strict allowlist	Production websites and APIs	`CORS_ALLOWED_ORIGINS` only
Regex allowlist	Multiple subdomains	`CORS_ALLOWED_ORIGIN_REGEXES`
Dev permissive	Local testing only	Use allowlist for localhost, never wildcard in prod

Production anti-patterns

CORS_ALLOW_ALL_ORIGINS = True in prod.
Allowing credentials + wildcard origin.
Letting any custom header through “just to make it work”.

Cookies, sessions, and auth

Cross-origin requests with cookies require both CORS and browser cookie rules to align. Most “it still fails” cases are actually cookie policy issues.

If you use session cookies across origins

CORS side

CORS_ALLOW_CREDENTIALS = True

With credentials, origin must be explicit (no wildcard).

Cookie side (browser rules)

Use HTTPS in prod, and ensure cookies allow cross-site usage when needed.

Cookies must be compatible with modern SameSite constraints.

Token auth (Authorization header)

If your frontend sends Authorization: Bearer ..., the browser will preflight. Ensure Authorization is allowed, and that OPTIONS returns correct allow headers.

Nginx / reverse proxy notes

In most setups, Django-CORS-Headers is enough. But proxies can break preflight if OPTIONS is mishandled, or if headers are stripped.

Proxy pitfalls checklist

OPTIONS requests returning 405/404 at the proxy layer.
Proxy removing Access-Control-* headers.
Caching preflight incorrectly.
Different CORS policy for /api vs /media endpoints.

Rule of thumb

Let Django set CORS headers consistently. Only implement proxy-level CORS if you really need it, and keep it aligned with Django settings.

Troubleshooting: symptom → cause → fix

Symptom	Likely cause	Fix
Blocked by CORS policy (no allow origin)	Origin not in allowlist, middleware not active	Whitelist exact origin, ensure CorsMiddleware is high in MIDDLEWARE
Preflight OPTIONS fails (405/404)	Proxy blocks OPTIONS or route missing	Allow OPTIONS through proxy, ensure Django responds with headers
Credentials mode fails	Wildcard origin, missing allow credentials	Set explicit origins + `CORS_ALLOW_CREDENTIALS=True`
Authorization header blocked	Allowed headers missing authorization	Add `authorization` to allowed headers
Works in curl, fails in browser	CORS is enforced only by browsers	Fix CORS headers; curl bypasses browser policy
Some endpoints work, others fail	Different middleware stack or path rules	Ensure consistent settings and routing for /api/**

Quick verification steps

Open browser devtools → Network → find OPTIONS request.
Check response headers include Access-Control-Allow-Origin.
Confirm allowed headers include Authorization (if used).
Confirm origin matches exactly (scheme/host/port).
Check proxy logs for 405/404 on OPTIONS.

Links

Keep this section stable: official docs, repository, package page.

IDEO-Lab integration notes

• If you split front and API across subdomains, document the exact allowed origins in your deployment notes.

• Avoid wildcard origins; keep per-env allowlists (dev/staging/prod).

• Prefer token auth for APIs; if using cookies cross-site, align cookie policy carefully.

WhiteNoise Static Deploy Cache

Serve static files in production — without extra infrastructure

WhiteNoise lets your Django app serve its own static files efficiently, with proper caching, gzip/brotli compression, and versioned filenames. It’s ideal when you want a clean deploy without having to maintain a separate static server or object storage setup.

What it solves (concrete)

Static delivery with immutable caching (hashed filenames).
Compression (gzip/brotli) with correct headers.
One-process deploys: no need for separate static service.
Simple scaling: every web instance serves the same collected assets.
Great default for “classic” Django deployments (VMs/containers).

When NOT to use it

Huge static traffic at scale → prefer CDN + object storage.
Multi-region static distribution → CDN becomes mandatory.
Strict separation of concerns enforced by platform.
Ultra heavy assets (video, large downloads) → storage/CDN.

Ideal fit (IDEO-Lab)

• Serve CSS/JS/icons for your dashboards and modals reliably.

• Keep deploy simple on EC2 instances (no extra bucket/CDN required to start).

• Later upgrade path is clean: move static to S3/CloudFront if traffic grows.

Mental model

collectstatic
                        -> STATIC_ROOT (a folder with all assets)
                        -> WhiteNoise serves /static/* directly from that folder
                        -> adds cache headers + compression + immutable versioning

Install

1) Install package

pip install whitenoise

2) Middleware order matters

WhiteNoise middleware should be placed right after SecurityMiddleware (classic recommended placement).

MIDDLEWARE = [
                            "django.middleware.security.SecurityMiddleware",
                            "whitenoise.middleware.WhiteNoiseMiddleware",
                            # ...
                            ]

3) Make sure collectstatic runs

python manage.py collectstatic --noinput

Minimum settings checklist

STATIC_URL set (usually /static/)
STATIC_ROOT set (a real directory)
collectstatic executed during deploy/build
web process can read STATIC_ROOT

Configuration (recommended)

Storage backend for hashed filenames

Hashed filenames enable long caching without “stale assets after deploy”.

STORAGES = {
                    "staticfiles": {
                    "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"
                    }
                    }

Why Manifest storage matters

Build produces unique filenames (content hash).
Browsers can cache “forever”.
Deploying a new version does not break cache.
Compression variants (gzip/brotli) handled cleanly.

Common pitfall

If manifest storage is enabled and a referenced asset is missing, Django can raise an error during template rendering. That’s a good thing: it forces your build to be consistent.

Static root baseline

STATIC_URL = "/static/"
                    STATIC_ROOT = BASE_DIR / "staticfiles"

Caching & compression strategy

The whole point of WhiteNoise is correct caching. You want immutable assets to be cached long, and non-hashed assets to be cached short.

Asset type	Cache policy	How to achieve
Hashed (manifest)	Very long (immutable)	Use `CompressedManifestStaticFilesStorage`
Non-hashed	Short cache	Ensure you do not rely on non-hashed for core assets
Large JS/CSS bundles	Long + compression	Gzip/brotli variants served automatically

Best practice

Always reference assets using Django static helpers so hashed filenames are used. That’s how you avoid “users still see old JS after deploy”.

Nginx / CDN integration

Option A — WhiteNoise only

Simple VM deploy: Nginx reverse proxies to Django app; static served by WhiteNoise. Works well for moderate traffic.

Option B — Nginx serves /static

Nginx can serve static directly from STATIC_ROOT with very low overhead. WhiteNoise still helps for manifest build + compression generation, but runtime static is handled by Nginx.

Rule of thumb

Start with WhiteNoise for simplicity. If static traffic becomes large, move static to CDN/object storage, or let Nginx serve it directly.

Deploy playbook

This is the standard sequence that avoids 90% of issues.

#	Step	Goal
1	Install requirements	WhiteNoise available at runtime
2	Run collectstatic	STATIC_ROOT contains correct assets
3	Restart web process	New code serves new static build
4	Verify /static load	Confirm cache headers and correct paths
5	Watch for manifest errors	Catch missing assets early

Production checklist

STATIC_ROOT readable by app user.
Correct file permissions after deploy.
Manifest storage enabled for long cache.
Static URLs resolve with correct host/proxy settings.

Troubleshooting

Symptom	Likely cause	Fix
404 on /static/*	collectstatic not run or STATIC_ROOT wrong	Run collectstatic, verify STATIC_ROOT path and permissions
Static loads but is outdated	No hashed filenames or aggressive proxy cache	Enable manifest storage, use immutable caching, purge proxy if needed
Manifest error at runtime	Referenced asset missing from build	Fix build pipeline, ensure assets are included and collected
High CPU serving static	Huge static traffic hitting app	Move static to Nginx/CDN, keep WhiteNoise for build features

Quick validation

Open a static file URL directly in browser.
Check response headers: cache-control, content-encoding.
Confirm hashed filenames exist in STATIC_ROOT.
Verify deploy ran collectstatic after code update.

Links

Keep official docs here.

IDEO-Lab notes

• Perfect baseline for EC2 deployments before moving static to S3/CloudFront.

• Keep manifest storage enabled to avoid “broken JS/CSS after deploy”.

Django-Simple-History Audit History Compliance

Automatic model audit trail (who changed what, when, and from where)

Django-Simple-History creates “historical” rows for your models automatically. Each change (create/update/delete) generates a snapshot with metadata (timestamp, user, change type), so you can audit, rollback, compare versions, and build compliance-grade traces without custom tables.

What it gives you

Immutable audit trail: historical snapshots per change.
Who: history_user (if configured).
When: history_date.
What: history_type (+ create, ~ update, - delete).
Rollback: revert to previous version.
Diff: compare two versions (basic or custom).

Best use cases

Admin changes (critical configs, routing, templates).
Security ops tables (allow/deny lists, rules engines).
Content changes (CMS-like, portfolio, docs).
Client data modifications (traceability / incidents).
“Who edited this?” answers in seconds.

Audit != version control

Simple-History stores database-level snapshots. It does not replace git or schema migrations. It is designed for data change traceability, not source/version control.

Mental model

Model table:          app_model
                        History table:        app_historicalmodel

                        Save/delete on model
                        -> historical row created
                        -> includes all tracked fields + metadata (date/type/user)

Install

1) Install package

pip install django-simple-history

2) Add to settings

INSTALLED_APPS += ["simple_history"]

                            MIDDLEWARE = [
                            "django.middleware.security.SecurityMiddleware",
                            # ...
                            "simple_history.middleware.HistoryRequestMiddleware",
                            ]

3) Migrate

python manage.py migrate

Common install mistakes

Middleware missing → history_user not populated consistently.
Forgetting to run migrations after adding HistoricalRecords.
Tracking too many large fields → storage bloat.

Model integration

Basic: track a model

from django.db import models
                    from simple_history.models import HistoricalRecords

                    class Project(models.Model):
                    name = models.CharField(max_length=200)
                    status = models.CharField(max_length=50, default="active")
                    updated_at = models.DateTimeField(auto_now=True)

                    history = HistoricalRecords()

What gets stored

All model fields (unless excluded)
history_date
history_type
history_user (if middleware)
history_change_reason (optional)

Change reason (optional but gold)

Useful for admin operations and incident postmortems.

obj.history_change_reason = "Bulk status update"
                            obj.save()

Selective tracking (avoid bloat)

Data type	Recommendation	Reason
Large text fields	Exclude or track only when required	History table grows fast
Binary / file-like	Do not store raw content in history	Explodes storage and backup times
Computed/cache fields	Exclude	Noise, no audit value
Critical config fields	Always track	Incident traceability

Admin UX (history visibility)

In Django admin, Simple-History can provide a built-in “History” view to inspect changes per object. This is extremely useful for ops-grade auditing.

Admin integration baseline

from django.contrib import admin
                    from simple_history.admin import SimpleHistoryAdmin
                    from .models import Project

                    @admin.register(Project)
                    class ProjectAdmin(SimpleHistoryAdmin):
                    list_display = ("id", "name", "status", "updated_at")
                    search_fields = ("name",)

Operational checklist

Expose history for critical models only (signal > noise).
Require admin permissions; audit tables can contain sensitive data.
Encourage change reasons for bulk actions.

Query, diff, rollback

Read history for an object

obj = Project.objects.get(pk=1)

                    # Latest first
                    for h in obj.history.all()[:5]:
                    print(h.history_date, h.history_type, h.history_user_id)

Restore previous version (rollback)

obj = Project.objects.get(pk=1)
                    previous = obj.history.all()[1]   # example: previous snapshot
                    previous.instance.save()

Rollback warning

A rollback is a new change. It will create a new history row. That’s expected and desirable. Always validate side effects (signals, constraints, dependent objects).

Diff idea (practical)

A simple approach: compare field values between two history rows and build a “changed fields” list.

def diff_history(a, b, fields):
                    changes = []
                    for f in fields:
                    va = getattr(a, f)
                    vb = getattr(b, f)
                    if va != vb:
                    changes.append((f, va, vb))
                    return changes

Patterns (production)

Pattern A — “critical models only”

Track only models that matter for ops/security/compliance. Avoid enabling history on noisy tables that change constantly.

Pattern B — “add reason for bulk changes”

Enforce a change reason in admin actions or management commands when mass-updating data.

Audit-friendly tags

Useful to know where the change came from: admin, API, cron, importer, etc.

# Example: tag changes by execution context
                    obj.history_change_reason = "cron: nightly sync"
                    obj.save()

Performance & storage

History tables can grow quickly. Treat them like logs: plan retention and index strategy.

Risk	Impact	Mitigation
History bloat	DB size & backups increase	Track only critical models, avoid big fields
Slow history queries	Admin history pages become slow	Index by (object_id, history_date) if needed
Retention unclear	Infinite growth	Define retention policy + purge jobs

Retention note

Decide how long you keep audit history. Some domains require long retention, others do not. Retention should match business and compliance needs.

Troubleshooting

Symptom	Likely cause	Fix
history_user is always null	HistoryRequestMiddleware missing	Add middleware and ensure authentication is active
History not created on save	HistoricalRecords not added or migrations missing	Add field + run migrate
History tables huge	Tracking too many models/fields	Reduce scope, avoid large fields, define retention policy
Rollback causes side effects	Signals/constraints triggered on save	Validate in staging, implement controlled rollback procedures

Quick verification

Modify an object in admin.
Open the object “History” view.
Confirm history_type and history_date are set.
Confirm history_user appears (if logged in).

Links

Keep official references here.

IDEO-Lab notes

• Use for critical models: security rules, API keys metadata, automation configs.

• Add change reasons to cron/import pipelines for real audit value.

• Plan retention to keep MariaDB/PostgreSQL lean.

Django-Extensions manage.py Shell DevTools

The “power tools” pack for Django development

Django-Extensions adds a set of high-impact development utilities: an enhanced shell with auto-imports, a better dev server with debugging helpers, model graph generation, and a bunch of workflow commands that reduce “manual repetitive operations” in daily Django work.

Why it’s worth it

shell_plus: immediate productivity (auto-import models).
runserver_plus: better errors + debug improvements.
graph_models: generate diagrams for data model review.
show_urls: quickly inspect URL routing (big projects!).
shell_plus --print-sql: visibility for ORM query patterns.

Rule of thumb

Enable it in dev/staging, not necessarily in prod.
Keep it out of “minimal runtime” containers if required.
Use it for diagnosis, documentation, and dev speed.

Command mindset

"I need to inspect something quickly"
                        -> django-extensions usually has a command for it
                        -> faster than writing a one-off script

Install

1) Install package

pip install django-extensions

2) Add to settings

INSTALLED_APPS += ["django_extensions"]

Optional but recommended

IPython for an excellent shell experience.
Werkzeug for runserver_plus enhancements.
Graphviz for graph_models (diagrams export).

Minimalism warning

If you ship ultra-minimal production images, keep django-extensions in a dev-only requirements file. In classic EC2 deployments it’s usually fine to have it installed but not “used” in prod.

shell_plus

shell_plus starts an interactive shell and automatically imports your models and common Django utilities, saving minutes each time. On big codebases (like IDEO-Lab), this becomes a “daily driver”.

Most used commands

Start shell_plus

python manage.py shell_plus

Show SQL for ORM code

python manage.py shell_plus --print-sql

Practical use cases

Need	What to do	Value
Inspect a model quickly	shell_plus + query a few objects	Fast diagnosis without writing scripts
Understand ORM performance	--print-sql and check generated queries	Instant visibility on joins/scans
Run a one-off cleanup	Small controlled loop (careful!)	Safe, interactive operations

Operational safety rule

On production databases, use shell_plus only with extreme discipline (read-only by default mindset). For bulk changes, prefer management commands with logging + dry-run mode.

runserver_plus

runserver_plus improves the development server experience (better debug pages, tooling hooks). This is especially useful when you have complex templates, many apps, and you want faster “root cause” cycles.

Start dev server

python manage.py runserver_plus

Common enhancements

Richer debug output during development.
Helpful when debugging template issues, middleware stacks, and request flow.
Better dev ergonomics without changing production server (gunicorn/uwsgi).

Do not confuse environments

runserver_plus is for development/debug. In production, you still use your standard server stack (gunicorn + nginx, etc.).

graph_models & architecture visibility

graph_models generates diagrams of your data model. In large projects, it’s useful for review, documentation, onboarding, and “what depends on what” analysis.

Example: generate a PNG diagram

python manage.py graph_models myapp -o myapp_models.png

IDEO-Lab workflow idea

Generate one diagram per major app (NetGuard, PostFolio, Analyzer, etc.), store it as a static asset, and link it from your “Data Model” dashboard cards for instant navigation.

Top commands (high value)

Command	What it does	Best for
`shell_plus`	Auto-imports models/utilities into interactive shell	Daily inspection and quick ops
`runserver_plus`	Enhanced dev server experience	Debugging complex request flow
`show_urls`	List URL patterns for your project/apps	Large projects routing sanity checks
`graph_models`	Generate model diagrams (Graphviz)	Documentation + architecture reviews
`show_template_tags`	Inspect available template tags/filters	Template debugging
`print_settings`	Print effective settings values	Debug config differences per env

Practical tip

Use show_urls and print_settings when you debug “works in staging but not in prod” issues. Those two commands save hours.

IDEO-Lab patterns (real productivity)

Pattern A — “diagnose fast”

shell_plus --print-sql to understand ORM behavior
print_settings to validate environment config
show_urls to confirm routing at scale

Pattern B — “document the system”

Generate per-app model diagrams
Store diagrams as static assets
Link them from your IDEO-Lab dashboards

Safety reminder

django-extensions accelerates experimentation. For anything destructive, wrap it in a management command with logging, a dry-run option, and explicit confirmation in your workflow.

Troubleshooting

Symptom	Likely cause	Fix
Command not found	App not in INSTALLED_APPS / wrong venv	Add `django_extensions`, verify environment
graph_models fails	Graphviz missing	Install graphviz system package and retry
shell_plus not using IPython	IPython not installed	Install IPython for best experience
runserver_plus issues	Missing dev dependency	Install related optional packages; keep dev-only

Quick validation

Run python manage.py shell_plus and ensure models import.
Run python manage.py show_urls and check output is sane.
Try graph_models only if Graphviz is installed.

Links

Official references (stable).

IDEO-Lab notes

• Keep it enabled in dev: it will pay back immediately on a multi-app project.

• Use show_urls + print_settings for “configuration drift” debugging.

• Generate per-app model diagrams to enrich your architecture pages.

Django-Import-Export Admin Data CSV XLSX

Admin-grade import/export for CSV and Excel

Django-Import-Export adds robust import/export actions in Django Admin using “resources”. You can export selected rows, import files with preview/dry-run, map fields, handle FK relations, and enforce validation rules before committing changes.

What it solves (practical)

Export data from Admin to CSV/XLSX for reporting.
Import client lists, catalogs, configuration tables.
Preview changes before writing to the database.
Handle updates (match on id or business key).
Reduce custom “one-off scripts” for data ops.

When to be careful

Large datasets (performance + locks).
High-risk models (security configs, billing data).
Imports that can delete or overwrite silently.
PII columns (compliance and retention).

Golden rules

Always enable preview/dry-run first.
Require explicit permissions for import.
Use “business keys” for updates, not only IDs.
Validate and normalize columns before saving.
Log who imported what and when (audit).

Install

1) Install package

pip install django-import-export

2) Add to settings

INSTALLED_APPS += ["import_export"]

Optional extras

Use XLSX export/import only if your stack includes the required spreadsheet libraries.
Prefer CSV for massive imports (simpler, faster, more predictable).

Admin setup (fast path)

Minimal integration

from django.contrib import admin
                    from import_export.admin import ImportExportModelAdmin
                    from .models import Customer

                    @admin.register(Customer)
                    class CustomerAdmin(ImportExportModelAdmin):
                    list_display = ("id", "email", "status")
                    search_fields = ("email",)

Export behavior

Admin adds export actions (selected/all depending on config). Use resources to control columns and formats.

Import risk note

Import is a write path into the DB. Restrict permissions and enforce validation rules.

Resources (control columns & updates)

Define a Resource

from import_export import resources
                    from .models import Customer

                    class CustomerResource(resources.ModelResource):
                    class Meta:
                    model = Customer
                    fields = ("id", "email", "status", "created_at")
                    export_order = ("id", "email", "status", "created_at")

Attach Resource to Admin

from django.contrib import admin
                    from import_export.admin import ImportExportModelAdmin
                    from .resources import CustomerResource
                    from .models import Customer

                    @admin.register(Customer)
                    class CustomerAdmin(ImportExportModelAdmin):
                    resource_class = CustomerResource

Update strategy (business key)

Prefer updating rows based on a stable unique field (email, code, slug), not only on database IDs.

class CustomerResource(resources.ModelResource):
                    class Meta:
                    model = Customer
                    import_id_fields = ("email",)
                    fields = ("email", "status")

Validation & normalization

High-quality imports require strict validation. The best imports are boring: predictable columns, strict types, clear error messages, and safe defaults.

Risk	Typical cause	Mitigation
Wrong column mapping	Headers changed by users	Require exact headers, provide a template export
Bad types (dates, numbers)	Locale formats, Excel conversions	Normalize formats and validate strictly
Duplicates	No stable import key	Use business key in `import_id_fields`
Silent overwrites	Ambiguous matching	Reject if multiple matches are found

Playbook

Export a template from Admin.
Fill it with data (no extra columns).
Import with preview/dry-run.
Fix errors, re-import.
Commit only when validation passes.

Workflows (real ops)

Workflow A — Safe admin import

Only superusers can import.
Imports require a standard template.
Dry-run mandatory.
Audit record created (who/when/file hash).

Workflow B — Bulk updates

Match on business keys.
Reject unknown keys (fail fast).
Log changes count per field.
Optional: run in off-peak windows.

Large imports note

If the dataset is huge, consider moving the import to a management command / Celery job instead of Admin, to get progress tracking, batching, and better failure recovery.

Security & governance

Admin import/export is a powerful feature. Treat it like a privileged API endpoint.

Control	Why	Implementation idea
Restrict import permission	Prevents data corruption	Admin permissions + group restriction
Restrict exported fields	PII leak prevention	Resource fields whitelist
Audit who imported	Traceability	Record user + timestamp + file metadata
Validate headers and types	Stops garbage input	Strict mapping + normalization

Troubleshooting

Symptom	Likely cause	Fix
Import button not visible	Admin class not using ImportExportModelAdmin	Inherit from ImportExportModelAdmin or add mixin
Wrong columns exported	No resource configured	Define Resource fields and attach via resource_class
Updates create duplicates	No stable import key defined	Set import_id_fields to business key
Encoding issues	CSV encoding mismatch	Use UTF-8 and standardize export templates
Import is slow / times out	Huge dataset in Admin request	Move to async job or batch imports off-peak

Quick verification

Export a small dataset to confirm columns and encoding.
Re-import the same file as dry-run.
Confirm update matching works (business key).
Test permissions with a non-privileged staff user.

Links

Official references (stable).

IDEO-Lab notes

• Use it for controlled admin ops (small/medium datasets).

• For massive imports, prefer management commands + progress logging.

• Pair with audit/history for traceability on critical models.

Django-Guardian Permissions Auth Object-level

Object-level permissions for Django

Django’s built-in permissions are model-level (global): “can view any Project”, “can change any Report”. Django-Guardian adds object-level permissions: “user A can view Project #17, but not Project #18”. This is essential for multi-tenant apps, per-client access control, and fine-grained authorization.

Typical use cases

Multi-tenant dashboards: each customer sees only their objects.
Sharing objects: allow a user/team to access a specific record.
Per-project roles (owner/editor/viewer) inside the same model.
Private documents, notes, incident reports, audit items.
Admin delegation: let staff manage only assigned objects.

Key design rule

Define a clear permission strategy per model.
Prefer role-based mapping (owner/editor/viewer).
Keep object-perm checks consistent in code paths.
Watch query performance for large datasets.

Common pitfall

Object permissions are powerful, but they can become a performance and maintenance problem if you create huge numbers of per-object permission rows without a strategy.

Mental model

Model-level:   "can view Project"
                        Object-level:  "can view Project #17"

                        Guardian stores per-object permissions and helps query
                        "objects user can access".

Install

1) Install package

pip install django-guardian

2) Add app

INSTALLED_APPS += ["guardian"]

3) Add auth backend

Keep Django default backend, then add Guardian backend.

AUTHENTICATION_BACKENDS = [
                            "django.contrib.auth.backends.ModelBackend",
                            "guardian.backends.ObjectPermissionBackend",
                            ]

4) Migrate

python manage.py migrate

Permissions model strategy

Before writing code, decide how you want to model access. The best implementation is the simplest one that supports your product requirements.

Approach	Best for	Notes
Per-object perms (Guardian)	Sharing, delegated access, fine-grained rules	Powerful, but can create many rows. Use role mapping.
Tenant FK filtering	Strict multi-tenant partition	Simple and fast; combine with Guardian only for sharing exceptions.
Role table (owner/editor/viewer)	Most SaaS projects	Maps roles to permissions; can drive Guardian assignments.

Recommended pattern

Use tenant filtering for baseline isolation, and Guardian object-perms for “sharing” and “delegation”. This avoids creating object-perm rows for every single object in the system.

API examples

Assign permissions

from guardian.shortcuts import assign_perm, remove_perm

                    assign_perm("view_project", user, project)
                    assign_perm("change_project", user, project)

                    remove_perm("change_project", user, project)

Check permissions

user.has_perm("view_project", project)
                    user.has_perm("change_project", project)

Query objects user can access

This is the real killer feature: filter queryset to what the user is allowed to see.

from guardian.shortcuts import get_objects_for_user

                    qs = get_objects_for_user(user, "app.view_project")
                    # qs is a queryset of Project objects the user can view

DRF view pattern

from rest_framework.viewsets import ModelViewSet
                    from guardian.shortcuts import get_objects_for_user

                    class ProjectViewSet(ModelViewSet):
                    def get_queryset(self):
                    return get_objects_for_user(self.request.user, "app.view_project")

Query & performance

Object-level permission checks can be fast if you rely on queryset filtering (get_objects_for_user) instead of doing “N checks per object” in Python loops.

Anti-pattern	Why it hurts	Better approach
Loop objects and call has_perm repeatedly	N+1 permission queries	Use get_objects_for_user to filter at DB level
Create perms for every object for every user	Permission table explodes	Use tenant filtering + perms for exceptions
Complex dynamic rules in code	Hard to maintain, slow	Define stable roles + explicit assignments

Scalability tip

If you expect very large datasets, design around “tenant isolation” first. Use Guardian to enable sharing/delegation, not as the primary partitioning mechanism.

Admin patterns

In Admin, a common approach is to restrict queryset visibility to objects the user can view, and enforce object perms on change/delete actions.

Filter queryset by perms

from django.contrib import admin
                    from guardian.shortcuts import get_objects_for_user
                    from .models import Project

                    @admin.register(Project)
                    class ProjectAdmin(admin.ModelAdmin):
                    def get_queryset(self, request):
                    qs = super().get_queryset(request)
                    if request.user.is_superuser:
                    return qs
                    return get_objects_for_user(request.user, "app.view_project", klass=qs)

Operational note

Decide whether staff should see “nothing by default” or “tenant-scoped objects”. Keep admin behavior consistent across apps.

Security posture

Object-level permissions are part of authorization. They must be enforced in every access path (views, APIs, admin, background jobs).

Control	Why	Implementation idea
Enforce perms at queryset level	Avoid data leakage	Use get_objects_for_user in list endpoints
Enforce perms on detail endpoints	Protect object reads	Check has_perm on the object
Centralize permission names	Reduce mistakes	Constants or helper functions
Audit assignments	Trace who granted access	Track via admin logs or history on mapping models

Critical warning

Never rely on frontend hiding. Always enforce object perms server-side for every read/write path.

Troubleshooting

Symptom	Likely cause	Fix
has_perm always returns false	Guardian backend not configured	Add ObjectPermissionBackend to AUTHENTICATION_BACKENDS
Users see too many objects	Queryset not filtered	Use get_objects_for_user for list endpoints/admin queryset
Permissions table grows too fast	Assigning perms for every object	Use tenant filtering; assign perms only for sharing exceptions
Slow permission checks	N+1 checks in Python loops	Filter querysets at DB level instead

Quick validation

Assign a perm to a user on a single object.
Confirm user.has_perm(..., obj) returns true.
Confirm list endpoint uses get_objects_for_user filtering.
Test with a non-privileged user account.

Links

Official references (stable).

IDEO-Lab notes

• Great fit for per-client dashboards and “shared objects” features.

• For very large scale, keep tenant isolation as the baseline and use Guardian for exceptions.

• Pair with audit/history to track permission grants and changes.

Django-Two-Factor-Auth 2FA Security TOTP WebAuthn

Strong authentication for Django accounts

django-two-factor-auth adds a second factor to the login flow (most commonly TOTP), plus optional methods like hardware-backed authentication (WebAuthn) and backup tokens. It reduces account takeover risk dramatically, especially for admin and privileged users.

What you get

TOTP setup (QR provisioning, authenticator apps).
Second-step challenge during login.
Backup tokens for recovery.
Optional WebAuthn (security keys / passkeys) integration.
Per-user device management and enrollment UI.

Recommended scope

Admins and staff accounts first.
Users with elevated permissions next.
Optionally enforce for all accounts in sensitive apps.

Do not treat SMS as strong 2FA

SMS can be vulnerable to SIM swap and interception. Prefer TOTP or WebAuthn where possible, and always provide recovery tokens with strong operational controls.

Mental model

Password step
                        -> if user has 2FA enabled:
                        challenge step (TOTP/WebAuthn)
                        -> session established
                        -> else:
                        optional enrollment enforcement policy

Install

1) Install package

pip install django-two-factor-auth

2) Add apps

INSTALLED_APPS += [
                            "django_otp",
                            "django_otp.plugins.otp_totp",
                            "django_otp.plugins.otp_static",
                            "two_factor",
                            ]

3) Add middleware

Place OTP middleware after AuthenticationMiddleware.

MIDDLEWARE = [
                            "django.middleware.security.SecurityMiddleware",
                            "django.contrib.sessions.middleware.SessionMiddleware",
                            "django.middleware.common.CommonMiddleware",
                            "django.middleware.csrf.CsrfViewMiddleware",
                            "django.contrib.auth.middleware.AuthenticationMiddleware",
                            "django_otp.middleware.OTPMiddleware",
                            "django.contrib.messages.middleware.MessageMiddleware",
                            "django.middleware.clickjacking.XFrameOptionsMiddleware",
                            ]

4) URLs

from django.urls import include, path

                            urlpatterns = [
                            path("", include("two_factor.urls", "two_factor")),
                            ]

5) Migrate

python manage.py migrate

Auth flow (what changes)

Step	What happens	Failure mode
Username + password	Primary authentication (Django auth)	Brute force risk without rate limits
2FA challenge	TOTP code or WebAuthn assertion	Device lost, clock drift, mis-enrollment
Session established	User is authenticated and OTP verified	Session fixation if cookies not hardened
Manage devices	Add/remove devices, generate backup tokens	Recovery abuse if not controlled

Recommended UX

Enrollment required for staff/admin accounts.
Offer TOTP as default; offer WebAuthn if available.
Always generate and display backup tokens once.
Provide clear “lost device” recovery procedure.

Configuration patterns

Login URL alignment

Make sure your login URLs point to the two_factor login views where appropriate.

LOGIN_URL = "two_factor:login"
                    LOGIN_REDIRECT_URL = "/"
                    LOGOUT_REDIRECT_URL = "/"

Enforcement strategy

Policy	Best for	Notes
Optional 2FA	Public apps, low-risk	Encourage adoption with prompts
Required for staff	Most production systems	Enforce for admin and privileged roles
Required for everyone	High-risk environments	Ensure strong recovery and support processes

Integration tip

Treat OTP verification as a separate “security state”. Guard sensitive views with both authentication and OTP verification checks where required.

Recovery and backup tokens

Recovery is where most 2FA systems fail operationally. Plan it as seriously as the enrollment. Backup tokens must exist, but they must be protected.

Best practices

Show backup tokens only once at generation time.
Require re-authentication for device changes.
Notify users on device add/remove.
Log all recovery actions.

High-risk recovery

Manual reset flows must have identity verification steps. A weak “support reset” becomes the real bypass.

Operational checklist

Define who can reset 2FA for a user.
Define what evidence is required for a reset.
Log the reset request and the approver.
Force re-enrollment after reset.

Hardening

Control	Goal	Notes
Rate limit login and OTP endpoints	Stop brute force	Apply IP + account rate limits
Harden session cookies	Reduce session theft	Secure, HttpOnly, SameSite, short TTL for admin
Enforce HTTPS everywhere	Prevent interception	HSTS recommended
Device management protections	Prevent takeover	Re-auth required for device changes
Alerts and audit logs	Detection and response	Notify on new device, failed OTP attempts

Recommended minimum for admin

2FA required for all staff/superusers.
Short session lifetime for admin sessions.
Rate limiting on password and OTP entry.
Audit logs for enrollment and resets.

Troubleshooting

Symptom	Likely cause	Fix
OTP always rejected	Clock drift or wrong device enrollment	Sync server time (NTP), re-enroll device
OTP middleware not working	OTPMiddleware missing or wrong order	Place OTPMiddleware after AuthenticationMiddleware
Login loop after successful OTP	Session/cookie misconfiguration	Check cookie domain, secure flags, proxy headers
Users locked out too easily	No recovery path or strict policy without support	Enable backup tokens and document reset process

Quick validation

Confirm server time sync (NTP).
Enroll one test user and complete login.
Verify OTP middleware activation.
Test backup token usage.

Links

Official references (stable).

IDEO-Lab notes

• Enforce 2FA for staff and operational accounts first.

• Pair with audit/history for device enrollment and resets.

• Add rate limiting and alerting for failed OTP attempts.

Django-HTMX HTMX Frontend Partial HTML SSR

Dynamic pages with server-rendered HTML (no heavy frontend framework)

HTMX lets you build dynamic user interfaces by sending AJAX-like requests directly from HTML attributes (hx-get, hx-post, hx-target) and swapping HTML fragments into the page. With Django, this is a powerful “SSR-first” approach: fast iteration, simple deployments, and clean templates without a large JS bundle.

Why teams adopt HTMX

SSR with small partial updates (no full page reload).
Less JavaScript complexity (no SPA state machine).
Templates remain the source of truth.
Works extremely well with Django forms and validation.
Great for dashboards, admin-like UIs, tools pages.

When HTMX is not ideal

Highly interactive canvases (complex client rendering).
Offline-first apps with heavy client storage.
Real-time multiplayer UIs (specialized websockets).
Massive client-side data exploration (maybe SPA).

IDEO-Lab fit

HTMX is perfect for “tools dashboards”: filters, live search, pagination, inline edit, partial refresh panels, and modal-driven experiences without shipping a large frontend stack.

Mental model

User clicks a button
                        -> HTMX sends request (GET/POST)
                        -> Django returns HTML fragment
                        -> HTMX swaps fragment into target element

Install

1) Install django-htmx (optional but useful)

pip install django-htmx

2) Add app and middleware

INSTALLED_APPS += ["django_htmx"]

                            MIDDLEWARE = [
                            "django.middleware.security.SecurityMiddleware",
                            # ...
                            "django_htmx.middleware.HtmxMiddleware",
                            ]

3) Include HTMX client script

Use a pinned version in your base template. You can also host the file locally for maximum control.

<script src="https://unpkg.com/htmx.org@1.9.12"></script>

Common install mistake

If HtmxMiddleware is missing, you lose helper features like request.htmx. HTMX still works, but your server-side branching becomes more manual.

Core concepts

Attribute	Meaning	Practical use
`hx-get`	Send GET request	Live search, refresh panels, pagination
`hx-post`	Send POST request	Form submit, toggle switches, create/update
`hx-target`	Where to swap HTML	Update a table body, a card, a modal body
`hx-swap`	How to swap	Replace content, append rows, swap outerHTML
`hx-trigger`	When to send	keyup, change, load, custom events
`hx-indicator`	Loading indicator	Show spinner on async update
`hx-vals`	Extra params	Send additional context without hidden fields

Django pattern

Return full template for classic navigation, and return a partial template for HTMX requests. With django-htmx middleware, use request.htmx to branch safely.

Patterns that scale

Pattern A — Partial templates

Keep a base page template.
Extract replaceable blocks as partials.
Return partial on HTMX requests.

Pattern B — Progressive enhancement

Page works without JS.
HTMX adds faster updates.
Fallback links/forms still function.

Avoid

Do not create a new endpoint per UI micro-action without structure. Group actions by domain (search, list, edit) and keep templates predictable.

Examples (copy-ready)

Example 1 — Live search

<input
                    type="search"
                    name="q"
                    placeholder="Search..."
                    hx-get="/tools/search/"
                    hx-trigger="keyup changed delay:250ms"
                    hx-target="#results"
                    hx-swap="innerHTML"
                    >

                    <div id="results"></div>

Example 2 — Button action + partial refresh

<button
                    hx-post="/netguard/ip/block/"
                    hx-vals='{"ip":"203.0.113.10"}'
                    hx-target="#block-status"
                    hx-swap="outerHTML"
                    >Block IP</button>

                    <div id="block-status"></div>

Example 3 — Django view branching

from django.shortcuts import render
                    from django_htmx.http import HttpResponseClientRedirect

                    def tool_list(request):
                    items = []  # fetch items
                    template = "tools/_list.html" if getattr(request, "htmx", False) else "tools/index.html"
                    return render(request, template, {"items": items})

HTMX redirect tip

When a POST should navigate, prefer HTMX-friendly redirect responses to keep the flow smooth.

Security

Risk	Impact	Mitigation
CSRF on hx-post	Unauthorized writes	Use Django CSRF protection and include CSRF token
Auth bypass via partial endpoints	Data leakage	Same auth checks as full views
Overexposed actions	Privilege escalation	Permission checks on every endpoint

Do not trust "partial" endpoints

A partial endpoint is still a public HTTP endpoint. Always enforce authentication and permissions exactly like you would for a normal page view.

Performance

HTMX reduces bandwidth and improves perceived latency by updating only fragments. But you still need to design server-side queries efficiently.

Issue	Symptom	Fix
N+1 queries in partial views	Slow fragment refresh	Use select_related/prefetch_related
Too frequent triggers	Server load spikes	Use delay/debounce in hx-trigger
Large HTML fragments	Bandwidth still high	Return only needed markup

Rule

Each HTMX endpoint should be as optimized as a real API endpoint: fast queries, small responses, predictable caching when possible.

Troubleshooting

Symptom	Likely cause	Fix
No request sent	HTMX script not loaded	Check network tab and script tag location
Partial returns full page	No branching on request.htmx	Return partial template when request is HTMX
403 on hx-post	Missing CSRF token	Ensure CSRF token is included in requests
Swap updates wrong area	hx-target selector mismatch	Verify target id/class and swap mode

Debug tip

Use browser devtools: watch the HTMX request, inspect returned HTML, then verify the swap target. Most issues are just “wrong selector” or “wrong template returned”.

Links

Official references.

IDEO-Lab notes

• Perfect for live filters, “search-as-you-type”, partial refresh panels, and inline edits.

• Keep endpoints permission-checked and CSRF-protected.

• For modal-heavy pages, return partial modal bodies and swap into a stable modal container.

Django-Select2 Forms Widgets Autocomplete AJAX

Better select fields: search, tagging, multi-select, remote data

Django-Select2 integrates Select2 widgets into Django forms and admin: searchable dropdowns, multi-select, async loading for large datasets, and a UX that scales when your choices list becomes too large for standard HTML selects.

Why it matters

Search inside select fields (instant usability boost).
Supports huge datasets using AJAX rather than loading all options.
Cleaner UX for foreign keys and many-to-many relations.
Reduces user errors by guiding selection.
Works well for admin tools and internal dashboards.

Typical use cases

Large user list selectors (assignees, owners).
Tags, categories, labels (multi-select).
Country/city selectors with search.
Admin FK fields for big tables.
“Attach existing object” in modals.

Do not preload huge selects

If the choices list can be thousands of rows, preloading will break UX and performance. Use AJAX-backed widgets with server-side filtering.

Mental model

Small dataset:
                        -> classic Select2 with local options

                        Large dataset:
                        -> Select2 sends AJAX query (search term)
                        -> Django returns JSON results
                        -> Select2 renders dropdown

Install

1) Install package

pip install django-select2

2) Add to settings

INSTALLED_APPS += ["django_select2"]

3) Add URLs

The package provides endpoints used by AJAX widgets.

from django.urls import include, path

                            urlpatterns = [
                            # ...
                            path("select2/", include("django_select2.urls")),
                            ]

Static assets note

Ensure your project static pipeline is correct. In production, validate that Select2 assets load properly (CSS + JS). Missing assets is the most common “it does not work” cause.

Widgets

Django-Select2 provides widgets for classic select fields and model-backed select fields. Choose the widget based on dataset size and relationship type.

Widget type	Best for	Notes
Local select widget	Small fixed choices	Simple, fast, no AJAX
Model select widget	Foreign keys / M2M	Can be AJAX-backed for scale
Heavy select widget	Huge datasets	AJAX search, requires server-side filtering
Tagging	Labels/categories	Decide whether tags are free-form or constrained

Rule

If the user can type to search, always ensure your backend search is indexed and scoped (tenant/permissions), otherwise you will leak data or hurt performance.

AJAX autocomplete

AJAX widgets are the core feature for large tables. The browser sends a query string, the server returns paginated results, and Select2 renders them.

Example: Heavy select widget (ModelChoiceField)

from django import forms
                    from django_select2.forms import HeavySelect2Widget
                    from .models import Project

                    class TaskForm(forms.Form):
                    project = forms.ModelChoiceField(
                    queryset=Project.objects.all(),
                    widget=HeavySelect2Widget(
                    data_url="/select2/fields/auto.json"
                    ),
                    )

Important note

Do not expose global search results to unauthorized users. Autocomplete endpoints must be permission-checked and tenant-scoped like any API.

Operational checklist

Limit results per request (pagination).
Add a minimum input length (e.g., 2-3 characters).
Index search fields (name, code, email).
Scope results by tenant and permissions.
Cache frequent queries if needed.

Forms patterns

Pattern A — Dependent selects

Use one Select2 field to filter another (e.g., customer -> projects). This works great with HTMX for partial updates and keeps forms responsive.

Pattern B — Modal create + select

If an item does not exist, create it in a modal, then refresh Select2 options via AJAX. This is a high UX win on internal tools.

Admin note

In admin, Select2 improves FK/M2M fields dramatically. For very large tables, always switch to AJAX mode.

Performance

Issue	Symptom	Fix
No pagination	Slow responses, huge payloads	Paginate results server-side
Unindexed search field	DB CPU spikes on search	Add index to searched columns
Too broad query	Users see irrelevant results	Scope by tenant and add filters
Requests too frequent	Load spikes	Minimum input length + debounce

Recommended defaults

Minimum input length: 2-3 characters.
Results per request: 20-50.
Index the search column(s).
Scope by permissions and tenant.

Security

Risk	Impact	Mitigation
Autocomplete data leakage	Users infer hidden records	Permission-check and tenant-scope results
Enumeration via search	Attackers brute list names/emails	Rate limit, require auth, minimum input length
PII exposure in labels	Privacy risk	Return safe labels only (avoid full emails/phones)

Security rule

Treat Select2 AJAX endpoints as sensitive APIs. They must be authenticated, permission-checked, and rate-limited.

Troubleshooting

Symptom	Likely cause	Fix
Widget renders as plain select	JS/CSS assets not loaded	Fix static pipeline and ensure scripts load
AJAX calls return 404	URLs not included	Add `path("select2/", include(...))`
AJAX returns 403	Auth/CSRF issues	Require auth, ensure correct middleware and headers
Search is slow	Unindexed query	Add indexes, restrict search scope
No results	Filtering too strict or wrong field mapping	Inspect query, verify search fields and tenant scope

Debug tip

Open browser devtools, watch network requests while typing, and inspect JSON responses. Most issues are missing URLs, missing assets, or permission filtering.

Links

Official references.

IDEO-Lab notes

• Combine Select2 + HTMX for dependent selects and modal-driven workflows.

• Protect autocomplete endpoints like APIs: auth + perms + tenant scope.

• Index search columns to keep the UI instant.

Django-Jazzmin Admin Theme UI Responsive

Modern responsive theme for Django Admin

Jazzmin is a drop-in admin theme that modernizes Django Admin with a cleaner UI, better navigation, responsive layouts, and configurable branding. It is a high ROI addon for internal tools where Admin is used as a real “back office”.

Why it’s valuable

Improves admin usability immediately (less “legacy admin feel”).
Better menus and grouping for multi-app projects.
Cleaner list pages and forms (less visual clutter).
Branding: logos, titles, links, icons.
Good fit for mobile and narrow screens.

When to be cautious

If you rely on heavy admin CSS overrides.
If you have multiple custom admin themes.
If you ship a “minimal static assets” policy.
After major Django upgrades (verify theme compatibility).

IDEO-Lab fit

On a multi-app platform, Jazzmin helps staff find the right models faster. Combine with django-import-export, simple-history, and strict permissions for a strong “ops admin”.

Install

1) Install package

pip install django-jazzmin

2) App order is critical

Jazzmin must be placed before Django Admin to override templates and assets.

INSTALLED_APPS = [
                            "jazzmin",
                            "django.contrib.admin",
                            "django.contrib.auth",
                            "django.contrib.contenttypes",
                            "django.contrib.sessions",
                            "django.contrib.messages",
                            "django.contrib.staticfiles",
                            # ...
                            ]

3) Collect static (production)

python manage.py collectstatic

Fast validation

Restart server.
Open /admin/.
Confirm visual theme is applied.
Confirm static files load (no 404 in devtools).

Configuration

Jazzmin is configured via settings. Start simple: branding + menu organization.

Minimal settings

JAZZMIN_SETTINGS = {
                    "site_title": "Admin",
                    "site_header": "Admin",
                    "site_brand": "Back Office",
                    "welcome_sign": "Welcome",
                    "copyright": "Company",
                    "topmenu_links": [
                    {"name": "Home", "url": "/", "permissions": ["auth.view_user"]},
                    ],
                    "show_sidebar": True,
                    "navigation_expanded": True,
                    }

Logo and icons

Use static URLs so deployments remain predictable.

JAZZMIN_SETTINGS.update({
                    "site_logo": "img/brand/logo.svg",
                    "site_logo_classes": "img-circle",
                    "site_icon": "img/brand/favicon.ico",
                    })

Practical rule

Keep config minimal at first. Over-customization can make upgrades painful. Focus on structure and navigation, not pixel-perfect styling.

UI & navigation design

Large projects need structured navigation. Jazzmin supports custom side menus, grouping, icons, and “top menu” links. The goal is to reduce time-to-model for staff.

Menu structuring (recommended)

Section	What belongs there	Example
Operations	Incident, monitoring, security tables	NetGuard events, blocks, telemetry
Content	CMS-like models	Pages, templates, translations
Accounts	Users, groups, permissions	Auth, Guardian, 2FA devices
Data Tools	Bulk imports/exports, audit	ImportExport, History, job logs

Good admin UX goal

A staff user should reach any important model in under 2 clicks.

Ops & hardening

Jazzmin is “just UI”, but Admin itself is a critical attack surface. The best Jazzmin setup is one that also improves operational safety.

Control	Why	Implementation idea
Require 2FA for staff	Prevent admin takeover	Enforce 2FA enrollment for staff users
IP allowlist / VPN	Reduce exposure	Restrict /admin/ to trusted networks
Least privilege groups	Limit blast radius	Granular group permissions per app
Audit admin actions	Trace changes	Use history/audit logs and backups
Short admin sessions	Reduce session theft impact	Separate session policies for staff if needed

Hard rule

Admin should never be treated as a “public UI”. Protect it with defense-in-depth.

Compatibility & upgrade strategy

Admin themes can be sensitive to Django upgrades. Keep upgrades controlled and verify theme compatibility during staging.

Upgrade playbook

Pin Jazzmin version.
Upgrade in staging first.
Verify /admin/ pages and static assets.
Validate custom admin overrides.
Roll out with a rollback plan.

Customization rule

The more you override templates/CSS, the more upgrades hurt. Prefer configuration options over hacks.

Troubleshooting

Symptom	Likely cause	Fix
Theme not applied	INSTALLED_APPS order wrong	Put `jazzmin` before `django.contrib.admin`
Broken CSS or missing icons	Static files not collected or served	Run collectstatic and verify static routing
Custom admin pages look wrong	Template overrides not compatible	Review overrides and reduce custom CSS
After upgrade, admin layout breaks	Theme version mismatch	Pin versions; test compatibility in staging

Debug tip

Open browser devtools on /admin/, confirm CSS/JS requests succeed (no 404/500), then validate INSTALLED_APPS order.

Links

Official references.

IDEO-Lab notes

• Combine with 2FA + IP restrictions for a hardened admin surface.

• Group apps by domain to reduce navigation time.

• Prefer configuration settings over template hacks.

Django-Waffle Features Flags Rollout Safety

Feature flags for safe releases and experiments

Django-Waffle enables feature flagging: you can turn features on/off without redeploying, roll out gradually, target specific users/groups, and quickly disable risky changes in production. Feature flags are one of the best “safety valves” for fast-moving platforms.

What it is used for

Kill switch for risky features in production.
Gradual rollouts (limited audience first).
A/B testing and experiments (basic form).
Staging features behind flags until ready.
Tenant/customer-specific feature enablement.

Flag types (core)

Flag: boolean gate for a feature.
Switch: global on/off toggle.
Sample: percentage-based rollout.

Common failure mode

Flags can become permanent “dead code switches”. Create a cleanup policy: each flag has an owner, a purpose, and a removal date once the rollout is complete.

IDEO-Lab fit

Use Waffle for “safe deployments” across your many tools: new dashboards, new parsers, new admin flows. Pair it with logging/metrics so you can observe impact per flag state.

Install

1) Install package

pip install django-waffle

2) Add to settings

INSTALLED_APPS += ["waffle"]

3) Migrate

python manage.py migrate

4) Admin access

Waffle models appear in Django Admin: Flags, Switches, Samples. Restrict edit permissions to a small trusted group.

Flags model

The core concept is simple: check a flag around the code path. If it is enabled, run the new behavior. Otherwise, fall back to the stable behavior.

Type	Behavior	Use case
Switch	Global on/off	Emergency kill switch for a subsystem
Flag	Boolean gate, can target users/groups	Enable a feature for staff first, then for all
Sample	Percentage-based enablement	Roll out to 5% then 25% then 100%

Naming convention

Use stable, descriptive names: dashboard_v2_enabled, parser_new_dedup, admin_bulk_export. Avoid ambiguous names like test1 or new_feature.

Usage

Python check

from waffle import flag_is_active

                    def view(request):
                    if flag_is_active(request, "dashboard_v2_enabled"):
                    # new path
                    pass
                    else:
                    # stable path
                    pass

Template check

{% load waffle_tags %}
                    {% flag "dashboard_v2_enabled" %}
                    <div>New UI</div>
                    {% else %}
                    <div>Old UI</div>
                    {% endflag %}

Switch and sample

from waffle import switch_is_active, sample_is_active

                    if switch_is_active("emergency_kill_switch"):
                    # disable subsystem behavior
                    pass

                    if sample_is_active("rollout_25_percent"):
                    # experiment path
                    pass

Avoid nested flag soup

Deeply nested flag logic becomes unmaintainable. Prefer one primary flag per feature, and remove flags after rollout completion.

Rollout playbook

A good rollout plan is a sequence of safe steps with clear rollback. Waffle gives you fast rollback: disable the flag.

Recommended rollout steps

Create the flag in admin, default OFF.
Deploy code with both paths (new + stable).
Enable for internal users only (staff group).
Monitor errors and performance for 24h.
Expand audience (sample 5% → 25% → 100%).
Remove legacy path and delete the flag.

Phase	Audience	What to watch
Phase 0	OFF	No behavior change; confirm stability
Phase 1	Staff	Errors, UX feedback, edge cases
Phase 2	Sample 5–25%	Latency, DB load, conversion, incidents
Phase 3	100%	Long-tail bugs, ops load

Ops & governance

Feature flags are operational controls. Treat them as part of release management.

Practice	Why	How
Flag ownership	Accountability	Assign an owner per flag (team or person)
Expiry policy	Prevent flag sprawl	Each flag has a removal date and ticket
Least privilege	Prevent abuse	Restrict edit rights in admin
Audit and logging	Trace changes	Log flag toggles and who changed them
Emergency procedure	Faster incident response	Document the kill switch list

Hard rule

Do not let every staff user edit flags. A single wrong toggle can break production behavior instantly.

Performance

Flag checks should be cheap, but naive usage can add DB queries. Use caching strategies and avoid checking the same flag repeatedly in tight loops.

Anti-pattern	Why it hurts	Fix
Check flag inside a loop	Repeated evaluations	Compute once per request and reuse
Many flags per template render	Complexity and overhead	Consolidate by feature groups
No caching	Extra DB reads	Enable cache backend and configure Waffle caching

Practical tip

If you already have Redis/Memcached, use it. Feature flags are a perfect caching use case.

Troubleshooting

Symptom	Likely cause	Fix
Admin models not visible	App not installed or migrations missing	Add `waffle` to INSTALLED_APPS and migrate
Flag check always false	Wrong flag name	Verify spelling and naming convention
Flag works in template but not in Python	Different contexts or request missing	Use request-based helpers consistently
Performance regression	Too many checks without caching	Enable cache; reduce repeated checks

Quick validation

Create a test flag in admin: waffle_smoke_test.
Wrap a visible UI element in a template flag block.
Toggle flag ON/OFF and confirm behavior changes instantly.
Confirm permissions prevent unauthorized edits.

Links

Official references.

IDEO-Lab notes

• Use flags to ship big UI changes safely (V2 dashboards, new parsers, new admin flows).

• Add an expiry policy and remove flags after rollout completion.

• Restrict editing to a small ops group and log changes.

Django-Silk Profiling Debug SQL Requests

Request and SQL profiling inside your Django app

Django-Silk is an in-app profiler that records HTTP requests, response timings, SQL queries (including timing), and helps identify performance regressions quickly. It is ideal for diagnosing slow pages, N+1 query issues, and unexpected backend work during requests.

Why it is useful

See slow endpoints and the exact SQL queries executed.
Spot N+1 patterns and missing select_related/prefetch_related.
Measure time spent in DB vs application logic.
Compare before/after changes when tuning views.
Quickly validate caching effectiveness.

When to use it

Staging or local profiling sessions.
Reproducing a “slow page” incident.
Measuring ORM query changes.
Validating pagination and filters.

Important warning

Silk adds overhead and stores request/SQL data. Do not run it permanently in production. Use it temporarily for controlled profiling and disable afterwards.

Mental model

Request comes in
                        -> Silk middleware records timing + metadata
                        -> DB queries are recorded with durations
                        -> Silk UI shows slow requests and query breakdown

Install

1) Install package

pip install django-silk

2) Add to settings

INSTALLED_APPS += ["silk"]

3) Add middleware (order matters)

Place Silk early enough to capture the full request, but after security basics if needed.

MIDDLEWARE = [
                            "django.middleware.security.SecurityMiddleware",
                            "django.contrib.sessions.middleware.SessionMiddleware",
                            "django.middleware.common.CommonMiddleware",
                            "django.middleware.csrf.CsrfViewMiddleware",
                            "django.contrib.auth.middleware.AuthenticationMiddleware",
                            "django.contrib.messages.middleware.MessageMiddleware",
                            "django.middleware.clickjacking.XFrameOptionsMiddleware",
                            "silk.middleware.SilkyMiddleware",
                            ]

4) URLs

from django.urls import include, path

                            urlpatterns = [
                            # ...
                            path("silk/", include("silk.urls", namespace="silk")),
                            ]

5) Migrate

python manage.py migrate

Fast validation

Restart server.
Browse a few pages to generate requests.
Open /silk/ and confirm requests appear.
Open one request and inspect SQL query timings.

What it captures

Signal	What you learn	Typical action
Request timing	Which endpoints are slow	Focus tuning on top offenders
SQL queries + durations	ORM work and DB cost	Fix N+1, add indexes, reduce joins
Headers / status / path	Traffic shape and errors	Find abusive endpoints or unexpected callers
SQL count per request	Chatty views	Prefetch, cache, restructure view
Request body (careful)	Inputs that trigger slow paths	Reproduce and test fixes

Privacy warning

Profilers can capture sensitive data (headers, POST bodies). Always restrict access and avoid running with broad capture on real user traffic.

Workflow (how to use it well)

A consistent workflow turns profiling into fast decisions instead of guesswork.

Profiling loop

Reproduce the slow request (same filters, same dataset).
Open the request in Silk and note total time.
Check SQL section: count, slowest query, duplicates.
Decide: ORM fix vs index vs caching vs pagination.
Apply fix and re-run the exact request.
Compare before/after timings and query count.

Finding	Interpretation	Fix examples
High SQL count	N+1 or chatty ORM	select_related / prefetch_related / annotate
One very slow SQL query	Missing index or bad plan	Add index, reduce scope, add pagination
Slow but few queries	Python work / serialization	Reduce payload, cache, optimize loops
Time spikes on filters	Unindexed filter columns	Index filters used in list pages

Common cases

Case 1 — N+1 queries

Many similar queries per request, often per row in a list. Fix with select_related for FK and prefetch_related for M2M/reverse relations.

Case 2 — Missing pagination

A list view loads thousands of rows. Fix by enforcing limits, pagination, and avoiding expensive ordering.

Case 3 — Slow filters

The query is fast without filters, slow with filters. Usually missing indexes on filter columns.

Case 4 — Serialization overhead

DB is fast, but request is slow. Optimize Python: reduce payload, avoid heavy template loops, cache derived computations.

Safety (do it right)

Risk	Impact	Mitigation
Data exposure	Leak headers/POST bodies	Restrict access, sanitize capture, run on staging
Performance overhead	Slows down requests	Enable only temporarily, sample traffic if possible
Public endpoint exposure	Attack surface	Protect `/silk/` by auth and IP rules

Recommended rule

Never expose Silk UI to the public internet. Lock it to staff accounts and trusted networks.

Performance impact

Silk adds overhead per request and also stores profiling data in your database. Keep profiling windows short and use cleanup.

Concern	Symptom	Fix
DB growth	Silk tables grow fast	Limit window, cleanup old rows
Overhead too high	Requests slow down	Disable Silk when not profiling
Noise	Too many irrelevant requests	Use ignore paths or filters

Best practice

Enable Silk on staging, reproduce the issue, extract insights, then disable it. Treat it as a diagnostic tool.

Troubleshooting

Symptom	Likely cause	Fix
/silk/ returns 404	URLs not included	Add `path("silk/", include(...))`
No requests recorded	Middleware missing	Add `silk.middleware.SilkyMiddleware`
Access denied	Auth restrictions	Ensure staff permissions and correct login
DB grows too quickly	Profiling left enabled	Disable Silk after profiling; purge old rows

Debug tip

Check middleware order, then open the network tab and trigger a request. If the request shows up in /silk/, the integration is correct.

Links

Official references.

IDEO-Lab notes

• Perfect for ORM tuning sessions (N+1, pagination, missing indexes).

• Lock it down: staff-only + trusted networks, never public.

• Use short profiling windows and cleanup stored rows.

Django-Model-Utils Models Utils Mixins Fields

Small utilities that remove a lot of boilerplate in Django models

django-model-utils provides lightweight model mixins and fields commonly used across projects: timestamp tracking, “status” patterns, handy fields, and helpers for readable choices. It improves consistency across apps and reduces repetitive model code.

Why teams use it

Standardize fields like created and modified across apps.
Implement status/state machines in a clean, consistent way.
Reduce copy/paste in models and migrations.
Make admin and APIs more uniform (same fields everywhere).
Improve readability and maintainability of models.

Best fit

Multi-app platforms (shared conventions matter).
Internal tools with lots of CRUD models.
Projects where audit-like fields are common.
Apps that need status transitions (jobs, tasks, workflows).

IDEO-Lab fit

This library is ideal for “platform consistency”: a shared base model for timestamps, soft status states, and repeated fields that appear across many apps.

Install

1) Install package

pip install django-model-utils

2) Add to settings

Model-Utils is usually import-only; it does not require a dedicated Django app entry for most use cases. Keep your dependency pinned for stability.

# requirements.txt
                            django-model-utils==4.*

Project policy

Define one “platform base model” in your codebase that uses these mixins, rather than mixing patterns randomly across apps.

Mixins

Mixins are the main value of this library. They provide consistent behavior without rewriting the same fields and save logic everywhere.

Mixin	What it provides	Best use
`TimeStampedModel`	`created` and `modified` fields	Most persistent business entities
`StatusModel`	Unified “status” field pattern	Jobs, tasks, workflows, pipelines
`SoftDeletableModel`	Soft delete behavior (mark deleted)	When deletion must be reversible
`UUIDModel` (when used)	UUID primary key or id field pattern	Public identifiers, distributed systems

Example: timestamps

from django.db import models
                    from model_utils.models import TimeStampedModel

                    class Project(TimeStampedModel):
                    name = models.CharField(max_length=200)

Example: status model

from django.db import models
                    from model_utils.models import StatusModel
                    from model_utils import Choices

                    class Task(StatusModel):
                    STATUS = Choices("new", "running", "failed", "done")
                    name = models.CharField(max_length=200)

Avoid hidden complexity

Soft delete is a design decision. If you use it, you must ensure your querysets and admin views handle deleted rows consistently.

Fields

Model-Utils includes some convenience fields for common patterns where plain Django fields get verbose.

Field	Problem solved	Notes
`MonitorField`	Update a timestamp when another field changes	Useful for “status_changed_at” tracking
`SplitField`	One input, multiple stored values	Use carefully; can be surprising
`UUIDField` (legacy usage)	UUID support in older Django versions	Modern Django has native UUIDField

Example: monitor a field

from django.db import models
                    from model_utils.fields import MonitorField

                    class Job(models.Model):
                    status = models.CharField(max_length=32)
                    status_changed_at = MonitorField(monitor="status")

Operational value

Tracking “when a status changed” is extremely useful for incident timelines and job orchestration dashboards.

Choices

Choices helpers make enumerations readable and consistent, and help avoid duplicated strings scattered across code.

Example: readable choices

from model_utils import Choices

                    JOB_STATUS = Choices(
                    ("new", "new", "New"),
                    ("running", "running", "Running"),
                    ("failed", "failed", "Failed"),
                    ("done", "done", "Done"),
                    )

Design note

Prefer stable internal values for DB storage and keep display labels separate. This makes migrations and analytics easier.

Design patterns

Pattern	Why it helps	Example
Platform base model	Consistency across many apps	`BaseEntity(TimeStampedModel)` used everywhere
Status + timestamps	Better operational visibility	StatusModel + MonitorField for transitions
Soft delete + audit	Accidental deletion recovery	SoftDeletableModel + admin filters
Public ids	Do not expose sequential primary keys	UUID or short public token field

Rule

Model-Utils should reinforce your conventions, not replace architecture. Standardize your base models and apply them across apps.

Pitfalls

Symptom	Likely cause	Fix
Soft-deleted rows still visible	Querysets not filtering deleted items	Use consistent managers and admin filters
Status transitions not tracked	No transition timestamp field	Add MonitorField and use it in dashboards
Choice values keep changing	DB values not stable	Use stable internal values; change labels only
Too many base classes	Mixin stacking without plan	Define one platform base model and reuse

Quick checklist

Do all core models have created/modified?
Do workflow models have a status + transition timestamps?
Are choice values stable over time?
Is soft delete used consistently (or not used at all)?

Links

Official references.

IDEO-Lab notes

• Use it to enforce model consistency across apps (timestamps + status patterns).

• Pair with audit/history and observability for operational timelines.

• Avoid soft delete unless you fully commit to consistent query behavior.

Django-BAT (Bad Actor Tracker) Security Login Brute force Lockout

Track and block failed login attempts (anti brute-force)

Django-BAT is the “Bad Actor Tracker” layer for authentication endpoints. It records failed login attempts and applies lockouts when a threshold is exceeded. In practice, most projects use django-axes as the underlying engine (failed login tracking + blocking, with DB or cache backends, multiple lockout keys, cooloff, allowlists/blocklists). :contentReference[oaicite:2]{index=2}

What it protects

Django admin login
Public login form endpoints
API token/session login endpoints
Credential stuffing and bot-driven brute force

Core outcomes

Fewer successful credential guessing attacks
Less noise in auth logs
Faster incident response (clear lockout signals)
Reduced load on auth endpoints

Hard rule

Never rely on a single layer. Combine BAT/Axes with rate limiting at the edge (NGINX), and strong admin hardening (2FA, IP restrictions).

Install

Option A (recommended): use django-axes

Upstream, widely used, actively maintained. :contentReference[oaicite:3]{index=3}

pip install django-axes

Add to settings

INSTALLED_APPS += ["axes"]

Middleware

Ensure middleware is enabled so lockout checks are applied consistently.

MIDDLEWARE = [
                            # ...
                            "axes.middleware.AxesMiddleware",
                            ]

Migrate

python manage.py migrate

Fast validation

Open the login page.
Fail authentication a few times.
Confirm lockout behavior triggers (or logs show attempts recorded).
Confirm admin/staff access is not accidentally blocked (allowlist policy).

Policy design

Lockout policy is where most projects fail: too strict breaks real users, too weak does nothing. Use clear defaults, then tune using logs and attack patterns.

Setting goal	Recommendation	Notes
Attempt limit	5–10 failures	Lower for admin, slightly higher for public login
Cooloff time	15–60 minutes	Use progressive cooloff for repeated abuse
Lockout keys	IP + username (or IP + user agent)	Balance safety and NAT/shared IP risk
Allowlisting	Staff/VPN subnets	Protect operations from accidental lockouts
Visibility	Log + admin view	Security controls must be observable

Common pitfall

Blocking by IP only can punish legitimate users behind shared NAT (office, mobile carrier). Consider combining IP + username, and keep an allowlist for trusted ranges. :contentReference[oaicite:4]{index=4}

Configuration (Axes-style)

The snippet below is a pragmatic baseline. Tighten or relax based on real traffic. (Exact options depend on the package version; validate against your pinned documentation.) :contentReference[oaicite:5]{index=5}

# Security baseline (example)
                    AXES_FAILURE_LIMIT = 7
                    AXES_COOLOFF_TIME = 1  # hours (example)
                    AXES_LOCK_OUT_AT_FAILURE = True

                    # Lockout keys
                    AXES_ONLY_USER_FAILURES = False
                    AXES_LOCKOUT_PARAMETERS = ["ip_address", "username"]

                    # Safety valves
                    AXES_NEVER_LOCKOUT_WHITELIST = True
                    AXES_IP_WHITELIST = ["127.0.0.1"]  # add VPN / admin subnets
                    AXES_USERNAME_WHITELIST = []       # service users if needed

                    # Observability
                    AXES_VERBOSE = True

Admin-specific policy

Use a stricter lockout for /admin/ and require 2FA + IP restrictions for staff. Treat admin authentication as a different security tier.

Storage backends

Axes-style engines can persist attempts either in the database or in a cache backend for speed and resilience. :contentReference[oaicite:6]{index=6}

Backend	Pros	Cons / notes
Database	Easy to audit and query	Can grow quickly; needs cleanup/retention
Cache (Redis/Memcached)	Fast, good under attack	Less durable; still needs policy for visibility

Retention recommendation

If you store attempts in DB, apply retention (purge old attempts) and index the columns used for filtering (ip, username, timestamp) to keep admin views fast.

Ops & integrations

BAT/Axes is the application layer. It becomes much stronger when combined with edge controls and your platform security stack (rate limiting, firewall automation, incident dashboards).

Layer	Goal	Example
NGINX rate limit	Drop bot bursts early	limit_req on /login and /admin
Firewall automation	Block abusive subnets	Feed repeated offenders into NetGuard rules
2FA for staff	Prevent admin takeover	Enforce 2FA for staff accounts
Monitoring & alerting	Detect active attack	Alert on spike in failed logins

Incident playbook

Confirm spike in failures (logs / dashboard).
Enable stricter rate limiting on auth endpoints.
Lower attempt limit temporarily for /admin/.
Block top abusive IPs/subnets at firewall.
Review allowlist to protect staff access.
After incident: restore policy and purge old noise data.

Troubleshooting

Symptom	Likely cause	Fix
No lockouts happen	Middleware missing or misordered	Add `axes.middleware.AxesMiddleware`
Everyone gets locked out	Lockout key too broad (IP-only)	Use IP + username; add allowlist
Real IP not detected	Proxy headers not handled	Fix proxy config; validate client IP source
DB tables grow too fast	Retention not enforced	Add cleanup job / retention policy

High-impact check

If your app is behind a reverse proxy, verify your “real client IP” logic first. Otherwise lockouts may target the proxy IP and become meaningless.

Links

Upstream references (Axes engine).

IDEO-Lab notes

• Combine BAT/Axes with 2FA and IP restrictions for staff/admin.

• Feed repeat offenders into your firewall automation (NetGuard).

• Keep a retention job for DB-backed attempt logs.