Getting started
Adding real-time collaboration to your Django project
This tutorial assumes that you have tried out the Channels tutorial (at least part 1 and 3).
Install
pip install channels-yroom
Add apps to settings
Add "channels"
and "channels_yroom"
to INSTALLED_APPS
in your settings.
Setup consumer
Set up your WebSocket consumer in your app consumers.py
.
from channels_yroom.consumer import YroomConsumer
class TextCollaborationConsumer(YroomConsumer):
def get_room_name(self) -> str:
"""
Determine a unique name for this room, e.g. based on URL
"""
room_name = self.scope["url_route"]["kwargs"]["room_name"]
return "textcollab.%s" % room_name
async def connect(self) -> None:
"""
Optional: perform some sort of authentication
"""
user = self.scope["user"]
if not user.is_staff:
await self.close()
return
await super().connect()
Configure protocols in asgi.py
Hook your WebSocket patterns in your asgi.py
and add a "channel"
protocol router for the "yroom"
channel name:
# ...
application = ProtocolTypeRouter(
{
"http": get_asgi_application(),
"websocket": AllowedHostsOriginValidator(
AuthMiddlewareStack(URLRouter(textcollab.routing.websocket_urlpatterns))
),
}
)
Use a channel layer for inter-process communication
Warning: The In-Memory Channel Layer will not work with channels-yroom
!
Because the yroom
communication runs through a worker process, we need inter-process communication.
Configure the official Redis Channel Layer in your settings:
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [("127.0.0.1", 6379)],
},
},
}
Make sure to have a Redis server running.
Run yroom worker process
In addition to your webserver with WebSockets support (e.g. daphne or uvicorn), you need to run a channels worker. You can run the yroom
worker implementation that supports graceful shutdown:
python manage.py yroom