Cursor Rules Template: Django Channels Daphne Redis

Overview

This Cursor rules configuration is a Cursor AI template for a Django project that uses Django Channels, Daphne, and Redis as the channel layer. It targets the Django stack with asynchronous WebSocket consumers, Redis as the channel backend, and PostgreSQL via Django ORM. Paste the copyable .cursorrules block into your project root to guide Cursor AI during development and review.

When to Use These Cursor Rules

• Starting a new Django project with WebSocket support and a Redis-backed channel layer.
• Seeking stack-specific Cursor AI guidance for code structure, security, and testing.
• Preparing production-ready configuration and a deterministic project layout for Django Channels apps.
• Ensuring consistent coding style and linting across async Django components.

Copyable .cursorrules Configuration

[Framework]
name = 'Django'
stack = 'Django Channels Daphne Redis'

[Context]
description = 'Cursor AI rules for Django apps with Channels, Daphne, Redis'

[CodeStyle]
lint = 'ruff'
 formatter = 'black'
maxLineLength = 88

[Architecture]
rootDir = '.'
directories = ['django_project','apps/core','apps/api']

[Authentication]
auth = 'Django authentication; sessions; CSRF enabled'

[Database]
db = 'PostgreSQL'; orm = 'Django ORM'

[Testing]
framework = 'pytest-django'

[Prohibited]
doNot = ['exec shell commands', 'modify migrations manually']

Recommended Project Structure

django_project/
  manage.py
  django_project/
    __init__.py
    asgi.py
    routing.py
    settings.py
    urls.py
apps/
  core/
    __init__.py
    models.py
    consumers.py
    routing.py
  api/
    __init__.py
    views.py
    serializers.py
    consumers.py
requirements.txt
docker-compose.yml

Core Engineering Principles

• Explicit async boundaries between the HTTP and WebSocket stacks.
• Single-responsibility components with clear channel routing.
• Deterministic project structure for Django Channels apps.
• Testability and observability baked into the workflow.
• Security-first defaults: CSRF, secure cookies, proper auth handling.

Code Construction Rules

• All Django models and ORM usage must go through the Django ORM API; avoid raw SQL unless necessary and vetted.
• WebSocket consumers must be async, use channel layers with Redis, and avoid blocking I/O in consumer handlers.
• Directory and file naming should reflect app boundaries (apps/core, apps/api) and follow PEP8 naming.
• Use environment-based configuration for secrets; never commit secret keys.
• Linting and formatting are enforced via Black and Ruff; run pre-commit hooks locally.
• Do not use unsafe system calls or shell-sourced commands from Cursor AI in production configs.

Security and Production Rules

• Configure Redis with a strong password and TLS where possible; place credentials in environment variables.
• Set Django ALLOWED_HOSTS, CSRF_COOKIE_SECURE, SESSION_COOKIE_SECURE, and CSRF_TRUSTED_ORIGINS for production.
• Run Daphne behind a reverse proxy (e.g., Nginx) with HTTP/2 and TLS termination.
• Use per-environment settings, disable debug in production, and manage secrets via a safe vault.
• Limit WebSocket origins to allowed domains and enforce rate limiting on API endpoints.

Testing Checklist

• Unit tests for models and validators; mock Redis channel layers where appropriate.
• Integration tests for Channels routing and consumer behavior with a test Redis instance.
• End-to-end tests that cover WebSocket handshake, sending/receiving messages, and error handling.
• Lint and type checks; ensure pre-commit hooks pass in CI.
• CI should run pytest-django with a PostgreSQL test database and Redis tests when needed.

Common Mistakes to Avoid

• Using blocking I/O inside async consumers or handlers.
• Disabling CSRF protection for HTTP endpoints without valid security alternatives.
• Exposing Redis credentials or secrets in code or logs.
• Assuming Daphne is the only option; ensure proper ASGI server configuration and load balancing.
• Mixing DRF authentication in WebSocket consumers without clear session handling.

FAQ

What is a Cursor Rules Template for Django Channels Daphne Redis?

A Cursor Rules Template defines a structured set of constraints and conventions to guide Cursor AI when assisting Django apps using Channels and Redis. It includes a copyable .cursorrules block and stack-specific guidance for production, testing, and security.

How do I enable Redis-backed channel layers in Django Channels?

Configure the Django settings to use Redis as the channel layer backend (ASCii-compatible RedisServer with redis-py integration). Ensure REDIS_URL is read from environment and that channels_redis is installed. Use a private Redis instance and proper password protection.

Can I customize authentication for WebSocket routes in this template?

Yes. The template advocates Django's built-in authentication and session management for HTTP and WSS routes. For API-like WebSocket interactions, leverage signed cookies or token-based headers with caution, always validating origin and scope in consumers.

How do I run tests for Django Channels in this setup?

Use pytest-django with a test database and a Redis mock or test instance. Write tests for consumers and routing, and mock external services. Run tests as part of CI to ensure channel layer and ASGI behavior remains consistent.

How do I integrate Cursor AI with this Django project?

Place the copied .cursorrules block at the project root and configure Cursor AI to follow the stack-specific rules. Use the guidelines to drive code generation, validation, and review processes that respect Django Channels and Redis semantics.