Set Up Redis Caching in Craft CMS with DDEV: A Step-by-Step Guide

Starting a Craft CMS project is easy if you follow the Quick Start Guide in the documentation. You'll quickly be up and running with a basic server setup for local development with DDEV.

In this post, I'll expand on this starter setup by including Redis to handle your cache.

Why Would You Want Redis in Your Local Dev Environment?

Redis does caching in memory and reduces the load on your database. While this might not significantly impact your local development, I prefer my local development environment to mirror my production environment as closely as possible. You too? Keep reading.

Installing Redis in DDEV

We will follow the instructions in the DDEV Redis repo.

Install Redis into your DDEV project.

ddev get ddev/ddev-redis
ddev restart

This process creates a file in your .ddev directory called docker-compose.redis.yaml. You don't need to alter it.

Installing Redis in your Craft project

You also need to install Redis in your Craft project.

ddev composer require yiisoft/yii2-redis

Then, modify the config/app.php file in your Craft CMS installation.

See the original article for the full code block.

use craft\helpers\App;

return [
    'id' => App::env('CRAFT_APP_ID') ?: 'CraftCMS',
    'components' => [
        'cache' => static function() {
            $config = [
                'class' => yii\redis\Cache::class,
                'keyPrefix' => Craft::$app->id,
                'defaultDuration' => Craft::$app->config->general->cacheDuration,

                // Full Redis connection details:
                'redis' => [
                    'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost',
                    'port' => App::env('REDIS_PORT') ?: 6379,
                    'password' => App::env('REDIS_PASSWORD') ?: null,
                ],
            ];
            return Craft::createObject($config);
        },
    ],
];

You'll also need to update your .env variables. I have omitted the variable REDIS_PASSWORD because my local Redis does not need a password.

# Redis settings
REDIS_HOSTNAME=redis
REDIS_PORT=6379

Note that the hostname is redis, not ddev-myproject-redis. I mention this because I've seen confusion about the hostname used in your environmental variables. The container name is ddev-myproject-redis, but the network name inside the DDEV Docker configuration is redis.

Redis is Running, But the Craft Queue Isn't

If you ddev restart your Craft site should still be working, but the queue may not run jobs automatically as you might expect. This is because you haven't set up the Craft queue to run yet. In production, you'd probably set up a daemon to run craft queue/listen. See Robust Queue Job Handling in Craft CMS for details on how to do that.

Note: If you didn't set any of this up, but your queue jobs are clearing, it might be due to the default way Craft CMS handles jobs. Craft will attempt to run jobs automatically during a page load within the control panel when the runqueueautomatically is left at the default value of true. See the Craft documentation for more information. I suggest setting this value to false because having the queue run automatically in our dev environment without requiring a page reload is the goal.

We must set up something similar to a daemon on our DDEV site to run whenever we start the project. We can do that with a simple bash script.

Create a new file called start_craft_queue.sh. This should live at the base of your Craft installation, i.e., in the same directory as your craft, composer.json, and other files. Here's the content of the file.

See the original article for the full code block.

#!/bin/bash

# Set the PHP_IDE_CONFIG environment variable to tell PHPStorm to use the correct server name
# This is necessary for debugging to work correctly
export PHP_IDE_CONFIG="serverName=craft"

# Start the Craft queue listener
php craft queue/listen &> ./storage/logs/ddev-craft-queue.log &

This script starts the queue and creates a log file in the storage directory where Craft keeps its other log files.

The PHP_IDE_CONFIG environmental variable tells PHPStorm, the code editor I use, where to find the craft executable file. Without this line, you may see errors while debugging with xdebug in PHPStorm when a new job is added to the queue.

Next, this script file must be executed when you start your DDEV project. We'll do that using hooks. Open your .ddev/config.yaml and add the following.

See the original article for the full code block.

hooks:
    post-start:
    - exec: sudo echo alias ll=\"ls -lhA\" >> ~/.bashrc
    - exec: sudo chmod +x /var/www/html/start_craft_queue.sh
    - exec: sudo bash /var/www/html/start_craft_queue.sh

What Is This File Doing?

Looking at the contents above, you'll see that it adds an alias called ll to the .bashrc file. Having the ll alias is handy in day-to-day use, but initially, I had it there as a simple way to test if my post-start hooks were working. I've left it in this example so you can quickly check if it also works for you. You can use ddev ssh to go into the web container and type ll. If you see the files listed, you know your hooks are working.

I'm running the commands with sudo. Initially, I did not do this, but my script would not run as my local user. It would silently fail.

There is a problem when using sudo, though. Craft does not want you to run the craft command as the root user, but we need to here. Update the .env file in your project to tell Craft not to warn you about the sudo command usage. (Neglecting to set this environmental variable is the only time I see output in the ddev-craft-queue.log log file.)

Craft allow superuser equals true.

CRAFT_ALLOW_SUPERUSER=true

Now you can ddev restart, and your Redis queue should be running automatically in your local environment.

Check to See If It's Working

Open the Redis CLI using the following command.

ddev redis see el eye.

ddev redis-cli

Once in the container, you can enter monitor to see what activity is happening in Redis. Try navigating around your Craft control panel and watch the monitor window. You should see activity, which means your Redis setup is working as expected. Good luck!