Build a production-ready real-time Django app. Covers Channels architecture, WebSocket consumers, group messaging, authentication, Redis channel layer, and deployment with Daphne + nginx.
HTTP is request-response: the client asks, the server answers, the connection closes. That model cannot push — it cannot tell the browser "a new message arrived" without the browser asking first. WebSockets give you a persistent, bidirectional connection, and Django Channels is what lets a Django app speak it. This tutorial builds real-time features the production way: consumers, groups, an authenticated handshake, a Redis channel layer, and the scaling and reliability concerns that separate a demo from something you can ship.
Real-time features — live chat, notifications, presence indicators, collaborative editing, live dashboards — all share a need the request-response model cannot meet: the server must initiate communication. Polling (the client asking "anything new?" every few seconds) approximates this but wastes resources and adds latency, and long-polling is a fragile workaround. A WebSocket holds one connection open over which either side can send a message at any time, which is exactly what these features need. That said, WebSockets are not free: they hold a connection per client, complicate scaling and deployment, and add state to an otherwise stateless app. Reach for them when you genuinely need server-initiated, low-latency updates; for occasional updates, server-sent events or even periodic polling may be simpler and sufficient.
Traditional Django runs under WSGI, a synchronous interface built around the request-response cycle that has no concept of a long-lived connection. Channels runs Django under ASGI, the asynchronous successor, which can handle WebSockets, background protocols, and long-lived connections alongside ordinary HTTP. Adopting Channels means switching your deployment to an ASGI server like Daphne or Uvicorn, and structuring an ASGI application that routes HTTP to Django's normal view stack and WebSocket connections to your consumers. Understanding that ASGI is the layer making all of this possible clarifies why Channels touches your deployment and not just your code.
Where a Django view handles one HTTP request, a consumer handles the lifecycle of one WebSocket connection — connect, receive messages, disconnect. It is the core abstraction you write. An async consumer looks like this:
from channels.generic.websocket import AsyncJsonWebsocketConsumer
class ChatConsumer(AsyncJsonWebsocketConsumer):
async def connect(self):
self.room = self.scope["url_route"]["kwargs"]["room"]
await self.channel_layer.group_add(self.room, self.channel_name)
await self.accept()
async def disconnect(self, code):
await self.channel_layer.group_discard(self.room, self.channel_name)
async def receive_json(self, content):
await self.channel_layer.group_send(
self.room, {"type": "chat.message", "text": content["text"]})
async def chat_message(self, event):
await self.send_json({"text": event["text"]})
The shape mirrors a view's lifecycle but spread across connect, receive, and disconnect handlers, all async so a single worker can hold thousands of mostly-idle connections without a thread each.
Just as urls.py maps paths to views, Channels needs a routing layer mapping WebSocket paths to consumers, wired into the ASGI application alongside the HTTP handler. You define WebSocket URL patterns, point them at consumers with as_asgi(), and wrap them in the protocol router so HTTP and WebSocket traffic each go to the right place. This separation keeps your ordinary views untouched — they still run through the normal Django stack — while WebSocket connections take the asynchronous path. Getting the routing and ASGI application set up correctly is the main piece of boilerplate; once it is in place, adding new real-time features is just adding consumers and routes.
A single consumer instance handles one connection, but real-time features need connections to talk to each other — a message from one user must reach everyone in the room. The channel layer is the shared backplane that makes this possible, and in production it is backed by Redis. It provides two primitives: sending a message to a specific channel, and group messaging, where consumers join a named group and a single send fans out to all of them. Without a channel layer, each worker process is an island and a message received by one cannot reach connections held by another. With Redis behind it, the channel layer works across every worker and server in your fleet.
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {"hosts": [("127.0.0.1", 6379)]},
}
}
Groups are how nearly every real-time feature is built. A chat room is a group; the set of a user's open tabs is a group; everyone watching a live event is a group. A consumer adds its channel to a group on connect and removes it on disconnect, and any code — a consumer, a view, a Celery task — can broadcast to the group, reaching every member. This decouples the sender from the recipients: the code that publishes "order shipped" does not need to know who is listening or where their connections live, it just sends to the group and the channel layer handles delivery. Mastering the group pattern is most of what it takes to build real-time features well.
A WebSocket connection must be authenticated, and it is easy to get wrong because the WebSocket handshake is not an ordinary request. Channels provides authentication middleware that populates scope["user"] from the session, so a logged-in user is identified on connect; reject anonymous connections in connect() when the feature requires auth. For token-based clients, parse and validate the token during the handshake before accepting. Crucially, authorize on connect and check permission for each action, because a connection is long-lived and a user's rights might change during it. Treat the handshake as the security boundary it is — an unauthenticated WebSocket is as dangerous as an unauthenticated API.
Async consumers cannot call the synchronous Django ORM directly without blocking the event loop, which would stall every other connection that worker holds. Channels provides database_sync_to_async to run ORM queries in a thread pool from async code, and conversely async_to_sync to send to the channel layer from synchronous code like a view or a Celery task. Getting this boundary right is the most common source of bugs for newcomers: a forgotten wrapper either blocks the loop or raises a "you cannot call this from async" error. Keep database work behind database_sync_to_async, keep the consumer's own logic async, and the two worlds coexist cleanly.
Real-time updates rarely originate from the WebSocket itself — they come from elsewhere in your app. An order ships in a Celery task, and you want to notify the customer's open tabs; a comment is posted through an ordinary form view, and watchers should see it appear. From any synchronous code you reach the channel layer with async_to_sync(get_channel_layer().group_send)(...) and broadcast to the relevant group. This is the pattern that connects your real-time layer to the rest of the system: the WebSocket carries the message to the browser, but the event that triggers it can come from anywhere — a view, a signal, a background job, a webhook.
Features like "who is online" or "user is typing" require tracking connection state, which is trickier than it sounds because connections drop without warning — a closed laptop, a lost network. Track presence by recording membership on connect and removing it on disconnect, but do not trust disconnect to always fire; back it with a heartbeat or a Redis key with a TTL that the connection refreshes, so a vanished connection eventually expires from the presence set. Designing presence to be self-healing — assuming connections will disappear silently — is what keeps the "online" list accurate rather than slowly filling with ghosts.
WebSockets scale differently from HTTP because each connection is long-lived and stateful. A server holds open connections continuously, so capacity is measured in concurrent connections, not requests per second, and you cannot freely recycle workers without dropping everyone connected to them. The Redis channel layer lets you run many ASGI workers across many servers that all share groups, so a message sent on one server reaches connections on another. Plan for connection limits per worker, use a load balancer that supports WebSocket upgrades and sticky behavior where needed, and remember that a deploy drops every connection — clients must reconnect gracefully.
Networks are unreliable and connections will drop, so the client side must reconnect automatically with backoff, and your design must tolerate the gap. The key question is what happens to messages sent while a client was disconnected: a pure WebSocket delivers them to nobody. For features where missing an update matters, pair the live channel with a durable store — persist messages to the database and have the client fetch anything it missed on reconnect, using the WebSocket only for the live push. This "WebSocket for liveness, database for durability" pattern is what makes real-time features trustworthy rather than lossy.
Channels provides a WebsocketCommunicator that lets you connect to a consumer in tests, send messages, and assert on what comes back, all without a real network. Test the connection lifecycle, that authenticated and unauthenticated connections are handled correctly, that group messages fan out as expected, and that disconnect cleans up state. Because consumers hold state and interact with the channel layer, these tests catch a class of bug that is otherwise only found in manual clicking. Treat consumers as you would views — covered by automated tests — so real-time features can evolve without regressing.
Long-lived connections carry their own risks. Validate and authorize every incoming message, not just the connection, because a client can send anything once connected. Guard against a single connection flooding the server with messages by rate-limiting at the consumer. Check origin during the handshake to prevent cross-site WebSocket hijacking. And never trust client-supplied identifiers — a user joining a room must be authorized for that room, or one user reads another's messages by simply changing a room name. The same input-validation and authorization discipline you apply to HTTP endpoints applies to every WebSocket message, with the added wrinkle that the connection persists.
WebSockets are not always the right answer. If updates only ever flow from server to client — a live feed, notifications, progress updates — server-sent events are simpler, run over plain HTTP, reconnect automatically, and avoid the ASGI and scaling complexity. If updates are infrequent and latency is not critical, periodic polling is trivially simple and stateless. Choose WebSockets when you genuinely need bidirectional, low-latency communication; reaching for them by default adds operational weight that many features do not require. Matching the transport to the actual communication pattern keeps your system as simple as the problem allows.
A subtle production issue with persistent connections is the slow consumer: a client that cannot keep up with the messages you are sending, causing buffers to grow and memory to climb. In a high-throughput channel — a busy live feed — a few slow clients can accumulate large server-side queues. Handle this by bounding how much you will buffer per connection and dropping or disconnecting clients that fall too far behind, rather than letting an unbounded backlog consume memory. Designing for the slowest client, not the fastest, is what keeps a real-time system stable when connections span everything from fibre to a phone on a train.
The shape of the messages you send over a WebSocket is an API you will live with, so design it deliberately. Use a consistent envelope — a type field identifying the message kind, plus a payload — so the client can dispatch on type cleanly, and version it so you can evolve the protocol without breaking older clients still connected. Keep messages small and focused; a WebSocket is a stream of events, not a place to dump large objects. A well-structured message protocol makes both server and client code simpler and lets your real-time features grow without the message format becoming a tangle of special cases.
Developing WebSocket features benefits from the right setup. Run an ASGI server locally that mirrors production, and use browser dev tools, which show WebSocket frames in the network tab so you can watch messages flow in both directions. A small test client script that connects and exercises your consumers speeds up iteration without needing the full front-end. Because the connection is stateful and event-driven, being able to observe the actual frames being exchanged is invaluable for understanding what is happening, and it turns debugging a misbehaving real-time feature from guesswork into directly watching the conversation between client and server.
Persistent connections have a different cost profile than stateless HTTP, and it is worth understanding before you scale. Each open connection consumes server resources for its entire lifetime, not just during a request, so a service holding a hundred thousand connections is sizing for sustained concurrency rather than request throughput. This affects how you provision, how you load-balance, and how you plan capacity. Real-time features are wonderful for users, but they shift your cost model toward concurrent-connection capacity, and being aware of that from the start — rather than discovering it when connection counts climb — lets you architect and budget for real-time at scale deliberately.
Django Channels brings real-time, bidirectional communication to Django by running it under ASGI and giving you consumers to handle WebSocket lifecycles. The patterns that matter in production are: groups for fan-out (the backbone of chat, notifications, and live updates), a Redis channel layer so groups work across your whole fleet, an authenticated handshake treated as a real security boundary, and careful bridging between async consumers and the synchronous ORM. Broadcast to groups from views and tasks to connect real-time to the rest of your app, design presence and delivery to assume connections drop silently, and back the live channel with durable storage so nothing is lost on reconnect. Scale by connection count across shared workers, test consumers like views, and reach for WebSockets only when bidirectional low latency is genuinely needed — otherwise SSE or polling may serve you with far less complexity.