The Redis cache provider enables dotCMS to be used with Redis, an external cache service. For more information on cache providers in dotCMS, see the Cache Chaining documentation.
What is Redis?
Redis is an open source (BSD licensed), in-memory data structure store, used as database, cache and message broker. It supports data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs and geospatial indexes with radius queries.
The Redis server development reference version is Redis 2.8, running either on-premise or via Amazon Elasticache. The dotCMS Redis cache provider has also been tested with AWS Elasticache DNS-based failover (read replica promotion) for high-availability.
For more information about Redis, please visit the Redis Official Website.
Redis in dotCMS
A Redis cache provider is included with dotCMS, and may be used to customize the cache configuration. The Java client that dotCMS uses to communicate with Redis is called Jedis, which is a small, high performance, and robust Redis client. For more information about Jedis, see the Jedis GitHub Page.
The combination of Redis and Jedis offer many benefits, including:
- The caching server can be scaled independently and at runtime in order to add or remove cache capacity.
- It removes the dotCMS cache from the Java heap, which lowers the dotCMS memory requirement and may significantly speed up the Java GC.
- Cache “puts” and “removes” are network-wide.
- There is no external syncing mechanism that can fail.
- dotCMS servers can be restarted with their caches fully loaded.
- Provides a shared cache in cluster environments.
- Allows you to specify a Master/Slave environment (different servers to read/write the data from/to).
- Jedis offers a configurable pool of connections to access the Redis server.
- Amazon offers a cloud-based Redis infrastructure called ElastiCache that can scale your cache in the cloud.
Enabling Redis
There are 5 steps to enable Redis in dotCMS:
- Add the Redis configuration properties to the dotmarketing-config.properties file.
- See Redis Configuration Properties, below.
- Edit or add cache chain properties to specify the use of Redis for your cache regions.
- See Cache Chain Properties, below.
- Shut down your dotCMS instance.
- Start up your Redis server(s).
- Start dotCMS and verify that the Redis cache provider is working correctly.
Redis Configuration Properties
There are a number of parameters you can use to configure the bahavior of the Redis cache provider. When using the Redis cache provider, add the following properties to your dotmarketing-config.properties file. For more information on each of these properties, see the Redis official documentation.
Note:
- It is strongly recommended that you make all changes to the dotmarketing-config.properties file through a ROOT folder plugin.
- These parameters are not included in the dotmarketing-config.properties file that ships with dotCMS; you must manually add these properties to your configuration when you add the Redis cache provider to your cache chain configuration.
Required Properties
The following configuration properties are the minimum properties required for the Redis cache provider to work. Without these basic properties, dotCMS will not be able to connect to the Redis server.
## By default, Redis will run on localhost on port 6379.
redis.server.address=localhost
redis.server.port=6379
Additional Properties
The following additional configuration properties are optional; if they're not found in the configuration properties file, the default values (shown below) will be used. However it is recommended that you add them to your configuration to provide you with the flexibility to modify and optimize your Redis performance.
## Your access password, if required by your Redis server
redis.password=[YOUR-REDIS-PASSWORD]
## Timeout (in milliseconds) to access the Redis server
redis.server.timeout=100
## The max number of clients that can be allocated by the pool.
redis.pool.max.clients=100
## The max number of idle connections in the pool.
redis.pool.max.idle=20
## The min number of idle connections in the pool.
redis.pool.min.idle=5
## Test on Return. When set to true, the pool will attempt to validate each client before it
## is returned to the pool. Clients failing to validate will be dropped from the pool.
redis.pool.test.on.return=false
## Block When Exhausted. When set to false, and when the pool is exhausted, Redis will not
## block the caller until a new or idle resource becomes available.
redis.pool.block.when.exhausted=false
Splitting Read and Write Caches
Redis allows you to split read and write caches to different Redis instances. Note that this capability is not fully tested in dotCMS. But the configuration properties are provided in case you wish to test and implement this functionality on your own high traffic site. The following configuration parameters enable this capability.
## Write Instance
redis.server.write.address=localhost
redis.server.write.port=6379
## Read Instance
redis.server.read.address=localhost
redis.server.read.port=6389
Note:
- In Redis, the read server must be configured to act as a slave of the write (master) server for the read server to replicate everything written in the master server.
- If you add these configuration parameters, the redis.server.address and redis.server.port properties listed in the Required Parameters section (above) will be ignored.
Cache Chain Properties
For dotCMS to use Redis, you must add com.dotmarketing.business.cache.provider.redis.RedisProvider to the cache chain properties for the cache regions where you wish to use Redis. For example, to change the default chain to search the Redis cache instead of the default H2 cache, change the default chain as follows:
cache.default.chain=com.dotmarketing.business.cache.provider.caffeine.CaffeineCache,com.dotmarketing.business.cache.provider.redis.RedisProvider
For more information on how to configure cache regions to use the Redis cache provider, see the Cache Chaining documentation.