Installation and Configuration

Installation

If not already done, install the Redis server, using the installation tool offered by the operating system, such as aptitude, yum, port or install Redis from source.

Start the Redis service on your host

$ sudo service redis-server start

Check if Redis is up and accepting connections

$ redis-cli ping
PONG

Install Django Websocket for Redis. The latest stable release can be found on PyPI

pip install django-websocket-redis

or the newest development version from github

pip install -e git+https://github.com/jrief/django-websocket-redis#egg=django-websocket-redis

Websocket for Redis does not define any database models. It can therefore be installed without any database synchronization.

Dependencies

Configuration

Add "ws4redis" to your project’s INSTALLED_APPS setting

INSTALLED_APPS = (
    ...
    'ws4redis',
    ...
)

Specify the URL that distinguishes websocket connections from normal requests

WEBSOCKET_URL = '/ws/'

If the Redis datastore uses connection settings other than the defaults, use this dictionary to override these values

WS4REDIS_CONNECTION = {
    'host': 'redis.example.com',
    'port': 16379,
    'db': 17,
    'password': 'verysecret',
}

Note

Specify only the values, which deviate from the default.

If your Redis instance is accessed via a Unix Domain Socket, you can configure that as well:

WS4REDIS_CONNECTION = {
    'unix_socket_path': '/tmp/redis.sock',
    'db': 5
}

Websocket for Redis can be configured with WS4REDIS_EXPIRE, to persist messages published on the message queue for extended periods of time. This is advantageous in situations, where clients shall be able to access the published information after reconnecting the websocket, for instance after a page is reloaded.

This directive sets the number in seconds, each received message is persisted by Redis, additionally of being published on the message queue

WS4REDIS_EXPIRE = 7200

The default value is 3600. To turn off persistence, set this value to 0 and messages will expire immediate after (trying) to dispatch to the Websocket.

Websocket for Redis can prefix each entry in the datastore with a string. By default, this is empty. If the same Redis connection is used to store other kinds of data, in order to avoid name clashes you’re encouraged to prefix these entries with a unique string, say

WS4REDIS_PREFIX = 'ws'

By default, ws4redis.subscriber.RedisSubscriber is used to listen to websocket messages. In case you need an alternative implementation, extend w4redis.redis_store.RedisStore

WS4REDIS_SUBSCRIBER = 'myapp.subscriber.RedisSubscriber'

The following directive is required during development and ignored in production environments. It overrides Django’s internal main loop and adds a URL dispatcher in front of the request handler

WSGI_APPLICATION = 'ws4redis.django_runserver.application'

Ensure that your template context contains at least these processors:

TEMPLATE_CONTEXT_PROCESSORS = (
    ...
    'django.contrib.auth.context_processors.auth',
    # Django <=1.8:
    'django.core.context_processors.static',
    # Django >= 1.9:
    # 'django.template.context_processors.static',
    'ws4redis.context_processors.default',
    ...
)

Websocket for Redis allows each client to subscribe and to publish on every possible channel. To restrict and control access, the WS4REDIS_ALLOWED_CHANNELS options should be set to a callback function anywhere inside your project. See the example and warnings in Safety considerations.

Check your Installation

With Websockets for Redis your Django application has immediate access to code written for websockets. Change into the examples directory and start a sample chat server

./manage.py migrate
... create database tables
... answer the questions
./manage.py runserver

Point a browser onto http://localhost:8000/chat/, you should see a simple chat server. Enter a message and send it to the server. It should be echoed immediately on the billboard.

Point a second browser onto the same URL. Now each browser should echo the message entered into input field.

In the examples directory, there are two chat server implementations, which run out of the box. One simply broadcasts messages to every client listening on that same websocket URL. The other chat server can be used to send messages to specific users logged into the system. Use these demos as a starting point for your application.

Replace memcached with Redis

Since Redis has to be added as an additional service to the current infrastructure, at least another service can be safely removed: memcached. This is required by typical Django installations and is used for caching and session storage.

It’s beyond the scope of this documentation to explain how to set up a caching and/or session store using Redis, so please check django-redis-sessions and optionally django-redis-cache for details, but it should be as easy as installing

pip install django-redis-sessions

and adding

SESSION_ENGINE = 'redis_sessions.session'
SESSION_REDIS_PREFIX = 'session'

to the file settings.py. Here is a full description on how to use Redis as Django session store and cache backend.

Also keep in mind, that accessing session data is a blocking I/O call. Hence the connection from the websocket loop to the session store must use gevent, otherwise the websockets may block altogether. Therefore, if you for some reason you have to remain with your current session store, make sure its monkey patched with gevent.

Warning

Never store session data in the database in combination with Websockets for Redis!