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’m going to 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 #
Take a look at the GitHub repo for Redis in DDEV: https://github.com/ddev/ddev— redis. We’re going to follow these instructions.
Install Redis into your DDEV project:
ddev get ddev/ddev-redis
ddev restart
This will create a new 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
Next, you need to modify a file in your Craft CMS installation. Look for config/app.php
. I’ve added Redis like this:
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. Note that I leave out 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
and not ddev-myproject-redis
. I mention this specifically because I’ve seen some confusion about the hostname to use 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
at this point, your Craft site should still be working, but the queue won’t 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.
A note about how the queue works: If you see your queue jobs clearing at this point, 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 oftrue
. See https://craftcms.com/docs/5.x/reference/config/general.html#runqueueautomatically for more information. I suggest setting this tofalse
because having the queue run automatically without requiring a page reload is one of the goals here.
We need to set up something similar 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, in the same directory as your craft,
composer.json
, and other files. Here’s the content of the file:
#!/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.
There is a PHP_IDE_CONFIG
environmental variable which was added after this post was initially published. This tells PHPStorm 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 needs to be executed when you start your DDEV project. We’ll do that using hooks. Open your .ddev/config.yaml
and add the following:
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
If you already have a hooks section, just add the post-start commands instead.
What Is This File Doing? #
If you looked at the contents above closely, 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 see if my post-start
hooks were working. I’ve left it in this example so that you have an easy way to test if this is working for you too. You can ddev ssh
into the web container and type ll
. If you see files listed, you know that your hooks are working.
Notice that 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.
Craft does not like you to run the craft
command as the root user, but we need to here. Update the .env
in your project to allow the sudo
command to tell Craft not to warn you about the sudo
command. (Neglecting to set this environmental variable is the only time I see output in the ddev-craft-queue.log
log file.)
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 with the following command.
ddev redis-cli
Once you are in the container, you can enter monitor
to see what activity is happening in Redis. Try navigating around your Craft control panel and keep an eye on the monitor window. You should see activity, which means your Redis setup is working as expected. Good luck!