disredis 1.0

Distributed Redis Client (dis-redis) to enable real-time failover of redis masters to paired slaves

========================
Distributed Redis client
========================

Distributed Redis Client (disredis) to enable real-time failover of
redis masters to paired slaves, providing improved availability and reliability
where needed.

The DisredisClient class can be used in place of a StrictRedis client.
Instead of passing the host and port in, pass in a list of Sentinel addresses in
the form of "host:port". It will connect to the first responding Sentinel
and query it for masters that it knows about. These masters will become the
nodes that are sharded across. As long as the number of masters does not
change, the sharding will be stable even if there is a node failure.

Node failures are handled by asking the Sentinel for the updated master of
the given node. During the initial failure, some requests may error out
with a ConnectionError if they are made between when the node fails and
when Sentinel executes the fail-over procedure.

Redis and Sentinel Configuration
================================

We recommend using at least Redis version 2.6.13.

For testing you need a minimum of two sentinels and two redis instances
(one master and one slave) to test fail over.

For production we recommend at least two servers. Each server should run
two sentinels and at least one master and one slave redis instance,
running on opposite servers.
::
| Server One | | Server Two |
|----------------| |----------------|
| Sentinel01 | | Sentinel03 |
| Sentinel02 | | Sentinel04 |
| Redis01-Master | | Redis01-Slave |
| Redis02-Slave | | Redis02-Master |
| ... | | ... |

**Important:** If you are running on AWS please ensure your django servers
can connect to the internal IP of the AWS redis servers. AWS ec2 instances
resolve to their internal IP which results in sentinels returning the
internal IP when queried. To check the IP address of redis instances run
the following command:

redis-cli -p <SENTINEL PORT, e.g. 26379> sentinel masters

Example Sentinel Configuration:

port 26379 #Sentinel Port

sentinel monitor redis-Redis1 server1.com 6382 2
sentinel down-after-milliseconds redis-Redis1 60000
sentinel failover-timeout redis-Redis1 900000
sentinel can-failover redis-Redis1 yes
sentinel parallel-syncs redis-Redis1 1

sentinel monitor redis-Redis2 server2.com 6383 2
sentinel down-after-milliseconds redis-Redis2 60000
sentinel failover-timeout redis-Redis2 900000
sentinel can-failover redis-Redis2 yes
sentinel parallel-syncs redis-Redis2 1

Please check the redis documentation for more details on Redis and
Sentinel installation and configuration.

We also recommend using Supervisor or similar to manage the various
Redis and Sentinel instances.

Django Setup
============

Either download from github and run

python setup.py install

or

pip install disredis

Add the disredis code to the django app.

Add the following to django settings

SESSION_COOKIE_AGE = 2592000 # thirty days - Adjust to your needs

SESSION_REDIS_PREFIX = '<REPLACE - e.g. mysessions>'
SESSION_REDIS_HOST = 'localhost'
SESSION_REDIS_DB = 6

SESSION_ENGINE = 'disredis_sessions.session'

SESSION_REDIS_SENTINEL_URLS = [
'SENTINEL_SERVER:SENTINEL_PORT',
...]

Restart django to start using Redis for user sessions

Troubleshooting
===============

Ensure the django application servers can connect to the redis
and sentinel ports.

Run the following command on the redis servers to check all
redis instances are listed (check IP and master/slave status):

$ redis-cli -p <SENTINEL PORT, e.g. 26379> sentinel master