Package: django-instant
Django InstantWebsockets for Django withCentrifugo.Push events into public or private channels.Handle the events in javascript client-side.:sunny: Compatible: plug it on an existing Django instancewithout any modification in your main stackExamplePush events in channels from anywhere in the code:frominstant.producersimportpublish# Publish to a public channelpublish("public","Message for everyone")# Publish to a private channel with an event class setpublish("$users","Message in logged in users channel",event_class="important")# Publish to a group channelpublish("$group1","Message for users in group1")# Publish to the staff channel with an extra json data payloaddata={"field1":"value1","field2":[1,2]}publish("$staff","Message for staff",data=data)Quick startInstall the Django packagepip install django-instantAdd"instant"toINSTALLED_APPSand updateurls.py:urlpatterns=[# ...path("instant/",include("instant.urls")),]Install the websockets serverUsing the installerUse the Centrifugo installer management command (for Linux and MacOs):python manage.py installwsThis will download a Centrifugo binary release and install it under acentrifugodirectory. It will
generate the Django settings to use.Install manualyInstall the Centrifugo websockets server: see thedetailled docDownload a release https://github.com/centrifugal/centrifugo/releases/latest
and generate a configuration file:./centrifugo genconfigThe generatedconfig.jsonfile looks like this:{"v3_use_offset":true,"token_hmac_secret_key":"46b38493-147e-4e3f-86e0-dc5ec54f5133","admin_password":"ad0dff75-3131-4a02-8d64-9279b4f1c57b","admin_secret":"583bc4b7-0fa5-4c4a-8566-16d3ce4ad401","api_key":"aaaf202f-b5f8-4b34-bf88-f6c03a1ecda6","allowed_origins":[]}Configure the Django settingsUse the parameters from the installer's output or from Centrifugo'sconfig.jsonfile
to update your Django'ssettings.py:CENTRIFUGO_HOST="http://localhost"CENTRIFUGO_PORT=8001CENTRIFUGO_HMAC_KEY="46b38493-147e-4e3f-86e0-dc5ec54f5133"CENTRIFUGO_API_KEY="aaaf202f-b5f8-4b34-bf88-f6c03a1ecda6"SITE_NAME="My site"# used in the messages to identify where they come fromCreate channelsGo into the admin to create channels or create them programatically:frominstant.modelsimportChannelChannel.objects.create(name="superuser",level=Channel.Level.Superuser)Api: channel create parameters:name: the channel name. Required and uniquelevel: access authorization level for a channel:Public, Users, Groups, Staff, Superuser. Default:Superuseris_active: a boolean to disable a channelgroups: a list of authorized Django groups for a channelAvalailable endpoints/instant/login/: takes a username and password as parameter and will login the
user in Django and return a Centrifugo connection token/instant/get_token/: get a Centrifugo connection token for a logged in userThe two methods above return some connection information: a token for
the websockets connection, a Django csrf token and a list of authorized
channels for the user:{"csrf_token":"fvO61oyhcfzrW3SjPCYxYfzDAQFO6Yz7yaAQkxDbhC0NhlwoP1cecqLEYv8SCDLK","ws_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnZ2ciLCJleHAiOjE2M..","channels":[{"name":"public","level":"public"},{"name":"$users","level":"users"},{"name":"$group1","level":"groups"}]}/instant/subscribe/: get tokens for Centrifugo channels subscriptions
(doc)Publish methodThe required parameters arechanneland eithermessageordatapublish("$users","A message",data={"foo":"bar"},event_class="important",bucket="notifications")The other parameters are optionalJavascript clientSeveral options are available for the client sideUse the official Centrifugo js clientManage your websockets connection manually with the official Centrifugo js library:Centrifuge-jsUse the embeded client in a script tagIn a Django template:{% load static %}<scriptsrc="{% static 'instant/index.min.js' %}"></script><script>constinstant=$instant.useInstant();</script>Api docUse the npm clientA dedicatedclientis available from npm
to handle the messages and connections client side in javascript or typescriptExampleAnexamplewith a backend and a frontend is availableTestsTo run the tests:tox