Configuring Moodle Redis Cache Backend for High-Concurrency Performance

Problem: Database Bottlenecks Under Concurrent Load

Moodle's default file-based and database-backed caches create significant I/O overhead when hundreds of concurrent users request pages. Each request fetches session data, course metadata, and application state from MySQL or PostgreSQL, causing lock contention and slow response times.

The fix: move high-frequency cache operations to Redis, an in-memory data store that handles millions of operations per second with sub-millisecond latency.

Prerequisites

• Redis server running (local or remote) with sufficient RAM for your cache dataset
• php-redis extension installed and enabled on all Moodle web servers
• Write access to config.php in your Moodle root directory
• Administrator access to Moodle's web interface for cache mapping

Verify PHP-Redis Extension

Run this command on each web server to confirm the extension is loaded:

php -m | grep redis

Expected output: redis (the module name). If empty, install it:

# Debian/Ubuntu
sudo apt update && sudo apt install php-redis
# RHEL/CentOS/Rocky
sudo dnf install php-pecl-redis
# Then restart PHP-FPM or Apache
sudo systemctl restart php8.2-fpm  # adjust version

Define Redis Instance in config.php

Edit config.php and add the following block before the $CFG->wwwroot line:

redisoptions = array(
    'host' => '127.0.0.1',        // Redis server IP or hostname
    'port' => 6379,               // Default Redis port
    'database' => 0,              // Redis DB index (0-15)
    'prefix' => 'moodle_prod_',   // Unique prefix per Moodle instance
    'timeout' => 2.5,             // Connection timeout in seconds
    'read_timeout' => 2.5,        // Read timeout
    'persistent' => 1,            // Use persistent connections
    'serializer' => 1             // Use igbinary if available, else PHP
);

Critical settings:

• prefix: Prevents key collisions when multiple Moodle sites share one Redis server. Use a unique value per site (e.g., moodle_prod_, moodle_staging_).
• database: Isolate Moodle data from other applications using Redis DB indices (0-15).
• persistent: Set to 1 to reuse connections across requests, reducing handshake overhead.

Map Cache Types to Redis via Administration UI

Do not edit the database directly. Use the web interface to map specific cache definitions to your Redis store:

1. Log in as a Moodle administrator.
2. Navigate to Site administration > Development > Caching > Configuration.
3. Under "Configured store instances", verify your Redis instance appears with status "OK".
4. For each cache definition you want on Redis (recommended: Session cache, Application cache, Moodle cache, Language cache):
   1. Click the edit icon (pencil) next to the definition.
   2. In "Store used", select your Redis instance.
   3. Set "Mode" to "Primary" for session/application caches, "Secondary" for others if you want a fallback.
   4. Save changes.
5. After all mappings are saved, click Purge all caches at the top of the page to clear stale data.

Verification and Diagnostics

1. Cache API Status Check

Return to Site administration > Development > Caching > Configuration. Your Redis instance should show "OK" with green checkmarks for all mapped definitions.

2. Live Key Activity Monitoring

On the Redis server, run:

redis-cli monitor

Navigate your Moodle site. You should see SET and GET commands with keys prefixed by your prefix value (e.g., moodle_prod_session:abc123). Press Ctrl+C to exit.

3. Memory Usage Check

redis-cli info memory | grep used_memory_human

Monitor this over time. If memory approaches your maxmemory limit, Redis will evict keys per its policy (default: allkeys-lru), potentially logging users out or degrading performance.

Critical Limitations and Safeguards

• Session persistence: Redis restarts flush all sessions, logging out every user. For production, configure Redis persistence (appendonly yes in redis.conf) or use a replicated setup with Sentinel/Cluster.
• Network latency: If Redis is remote, ensure <1ms round-trip latency. Higher latency negates caching benefits. Co-locate Redis with web servers or use a local replica.
• Memory limits: Set maxmemory in redis.conf to 70-80% of available RAM. Reserve headroom for OS and Redis overhead.
• Multi-tenant isolation: Never share a Redis database index (database setting) between Moodle instances. Use unique prefixes and separate DB indices.

Rollback Procedure

If issues arise after enabling Redis:

1. In the Caching Configuration UI, change each mapped definition back to "Default" (file/db store).
2. Click Purge all caches.
3. Comment out or remove the $CFG->redisoptions block from config.php.
4. Verify site functionality returns to baseline.

Version Assumptions

This guide applies to Moodle 4.0+ with PHP 8.1+ and Redis 6.0+. The serializer option requires the php-igbinary extension for value 1; omit or set to 0 if unavailable.