Skip to main content

Websockets for Django with Centrifugo

Project description

Django Instant

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 for more info). 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

A dedicated javascript client is available to handle the messages and connections client side


An example with a backend and a frontend is available

Project details

Download files

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

Files for django-instant, version 2.2.0
Filename, size File type Python version Upload date Hashes
Filename, size django_instant-2.2.0-py3-none-any.whl (14.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-instant-2.2.0.tar.gz (9.8 kB) File type Source Python version None Upload date Hashes View

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 Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page