Skip to main content

Websockets for Django with Centrifugo

Project description

Django Instant

pub package

Websockets for Django with Centrifugo.

  • Push events into public or private channels.
  • Handle the events in javascript client-side.

:sunny: Compatible: plug it on an existing Django instance without any modification in your main stack


Push events in channels from anywhere in the code:

from instant.producers import publish

# Publish to a public channel
publish("public", "Message for everyone")

# Publish to a private channel with an event class set
publish("$users", "Message in logged in users channel", event_class="important")

# Publish to a group channel
publish("$group1", "Message for users in group1")

# Publish to the staff channel with an extra json data payload
data = {"field1":"value1","field2":[1,2]}
publish("$staff", "Message for staff", data=data)

Quick start

Install the Django package

pip install django-instant

Add "instant" to INSTALLED_APPS and update

urlpatterns = [
    # ...
    path("instant/", include("instant.urls")),

Install the websockets server

Using the installer

Use the Centrifugo installer management command (for Linux and MacOs):

python installws

This will download a Centrifugo binary release and install it under a centrifugo directory. It will generate the Django settings to use.

Install manualy

Install the Centrifugo websockets server: see the detailled doc

Download a release and generate a configuration file:
./centrifugo genconfig

The generated config.json file 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 settings

Use the parameters from the installer's output or from Centrifugo's config.json file to update your Django's

CENTRIFUGO_HOST = "http://localhost"
CENTRIFUGO_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 from

Create channels

Go into the admin to create channels

Avalailable 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 user

The 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 method

The required parameters are channel and either message or data

publish("$users", "A message", data={
        "foo": "bar"}, event_class="important", bucket="notifications")

The other parameters are optional

Javascript client

Several options are available for the client side

Use the official Centrifugo js client

Manage your websockets connection manually with the official Centrifugo js library: Centrifuge-js

Use the npm client

A dedicated client is available from npm to handle the messages and connections client side in javascript or typescript


An example with a backend and a frontend is available


To run the tests:


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-instant-4.0.1.tar.gz (13.7 kB view hashes)

Uploaded source

Built Distribution

django_instant-4.0.1-py3-none-any.whl (20.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page