WSGI vs ASGI — a practical breakdown¶
WSGI is enough for sync HTTP Django. ASGI is needed for WebSocket and an async runtime. In
notes_chat_appboth protocols coexist in a single Uvicorn process.
The short difference¶
| WSGI | ASGI | |
|---|---|---|
| Standard | PEP 3333 (2010) | A separate ASGI specification (not a PEP; version 3.0 in 2019) |
| Protocols | HTTP only | HTTP + WebSocket + HTTP/2 |
| Execution | Synchronous (blocking I/O) | Asynchronous (asyncio event loop) |
| File in the project | notes_project/wsgi.py |
notes_project/asgi.py |
| Server | Gunicorn, uWSGI | Uvicorn, Daphne |
| Suitable for | CRUD, forms, authentication | + WebSocket, real-time, streaming |
Where to find it in the project¶
notes_project/wsgi.py¶
# notes_project/wsgi.py
import os
from django.core.wsgi import get_wsgi_application
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'notes_project.settings')
application = get_wsgi_application()
# ↑ The standard Django WSGI callable
# Used if you run the app through Gunicorn:
# gunicorn notes_project.wsgi:application
#
# In notes_chat_app this file is NOT used in production —
# we use asgi.py and Uvicorn.
# The file is kept for compatibility (some platforms look for wsgi.py)
What's in it: one line of real code — application = get_wsgi_application().
It is a callable that accepts an environ dict and a start_response function. Never touch it without a reason.
notes_project/asgi.py¶
# notes_project/asgi.py
import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'notes_project.settings')
# CRITICAL: the FIRST line before any imports from notes_app
django_asgi_app = get_asgi_application()
# After get_asgi_application() it is safe to import models, consumers
from notes_project.routing import websocket_urlpatterns
application = ProtocolTypeRouter({
"http": django_asgi_app, # HTTP → regular Django
"websocket": AuthMiddlewareStack(
URLRouter(websocket_urlpatterns) # WebSocket → Consumer
),
})
What to change here:
- Add a new protocol (for example, "lifespan") — very rarely
- Replace AuthMiddlewareStack with your own middleware — if you need custom WS authentication
What NOT to change:
- The order: get_asgi_application() always comes first
- ProtocolTypeRouter — this structure is mandatory for Channels
notes_project/routing.py¶
# notes_project/routing.py
from django.urls import re_path
from notes_app import consumers
websocket_urlpatterns = [
re_path(
r'^ws/groups/(?P<group_pk>\d+)/chat/$',
consumers.GroupChatConsumer.as_asgi(),
),
]
What to change here:
- Add a new WebSocket URL → a new line in websocket_urlpatterns
- Change a URL pattern → edit the regex
- Hook up a new Consumer → consumers.NewConsumer.as_asgi()
Do not confuse it with notes_app/urls.py — that one is for HTTP URLs, this one is for WebSocket URLs.
notes_project/settings.py — key parameters¶
# settings.py — what relates to ASGI:
INSTALLED_APPS = [
'daphne', # ← FIRST: overrides runserver → ASGI
'channels', # ← Django Channels framework
# ...
]
# Specifies which ASGI callable to use:
ASGI_APPLICATION = 'notes_project.asgi.application'
# ↑ Change it only if you renamed asgi.py or moved it to another package
# Channel layer:
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [{
"address": os.environ.get('REDIS_URL'),
"socket_timeout": None,
"health_check_interval": 30,
}]
}
}
}
# ↑ Change: the Redis address, timeout parameters
How it starts in Docker¶
entrypoint.sh:
exec python -m uvicorn notes_project.asgi:application \
--host 0.0.0.0 --port 8001
Uvicorn:
→ loads notes_project/asgi.py
→ gets application = ProtocolTypeRouter({...})
On an HTTP request from nginx:
ProtocolTypeRouter: protocol = "http"
→ passes it to django_asgi_app (views, urls, templates)
On a WebSocket from nginx (Upgrade: websocket):
ProtocolTypeRouter: protocol = "websocket"
→ AuthMiddlewareStack → URLRouter → GroupChatConsumer
When to change what¶
| Task | File | What to do |
|---|---|---|
| Add a new HTTP URL | notes_app/urls.py |
path(...) in urlpatterns |
| Add a new WebSocket URL | notes_project/routing.py |
re_path(...) in websocket_urlpatterns |
| Add a new Consumer | notes_app/consumers.py |
A new class + routing.py |
| Change the Redis config | notes_project/settings.py |
CHANNEL_LAYERS["CONFIG"] |
| Change the WS middleware | notes_project/asgi.py |
Change AuthMiddlewareStack(...) |
| Add lifespan events | notes_project/asgi.py |
"lifespan": ... in ProtocolTypeRouter |
| Change WSGI (for gunicorn) | notes_project/wsgi.py |
Rarely needed |
Practical exercise¶
# Start the stack:
docker compose up -d
# 1. Make sure ASGI is working:
docker compose logs web | grep "Uvicorn running"
# 2. Open the chat in DevTools → Network → WS
# Make sure the WS connection is established (101 Switching Protocols)
# 3. Look at asgi.py and routing.py:
docker compose exec web cat notes_project/asgi.py
docker compose exec web cat notes_project/routing.py
What's next¶
More about Channels, async consumers and WebSocket: - 07 — Async and the WebSocket chat - Async and Realtime