From 1f2401b40e181e40c05987cd132e7082acffe3d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 14 Jan 2026 13:44:49 +0100 Subject: [PATCH 1/4] Added mentions about Valkey --- docs/getting_started/requirements.md | 2 +- docs/getting_started/troubleshooting.md | 8 ++++---- .../background_tasks.md | 4 ++-- .../cache/persistence_cache.md | 5 ++++- .../clustering/clustering.md | 10 +++++----- .../clustering/clustering_with_ddev.md | 8 ++++++-- .../performance.md | 13 +++++++------ docs/infrastructure_and_maintenance/sessions.md | 16 +++++++++------- .../support_and_maintenance_faq.md | 2 +- docs/snippets/page_block_cache_clear.md | 4 ++-- 10 files changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/getting_started/requirements.md b/docs/getting_started/requirements.md index 670da3ff34..96fbf52045 100644 --- a/docs/getting_started/requirements.md +++ b/docs/getting_started/requirements.md @@ -17,7 +17,7 @@ The following server requirements cover both running the software on-premise and For running on [[[= product_name_cloud =]]](https://www.ibexa.co/products/ibexa-cloud), where recommended configuration and support is provided out of the box, see separate [[[= product_name_cloud =]] section](#ibexa-cloud-requirements-and-setup) for further reading on its requirements. The minimal setup requires PHP, MySQL/MariaDB, Apache/Nginx, Node.js and `yarn`. -For production setups it's recommended that you use Varnish/Fastly, Redis, NFS/EFS/S3 and Solr/Elasticsearch in a [clustered setup](clustering.md). +For production setups it's recommended that you use Varnish/Fastly, Redis/Valkey, NFS/EFS/S3 and Solr/Elasticsearch in a [clustered setup](clustering.md). !!! caution "Recommended versions" diff --git a/docs/getting_started/troubleshooting.md b/docs/getting_started/troubleshooting.md index d91dcfc433..4a034b1349 100644 --- a/docs/getting_started/troubleshooting.md +++ b/docs/getting_started/troubleshooting.md @@ -54,17 +54,17 @@ if you tell Composer to download dev packages or to download from source. To avoid the error, check the stability of packages and avoid using `--prefer-source`. -## Redis sessions issues +## Redis/Valkey sessions issues ### Inconsistent cache/session data -If cache or session data inconsistent across web servers in Redis, see [Redis clustering](persistence_cache.md#redis-clustering), and make sure you only read/write to one active master instance at a time. +If cache or session data is inconsistent across web servers, see [Redis clustering](persistence_cache.md#redis-clustering), and make sure you only read/write to one active master instance at a time. ### Removed or refused sessions -If Redis sessions are removed or new sessions are refused. +If sessions are removed or new sessions are refused, it's recommended to use a separated instance for sessions, that either never runs out of memory or uses an eviction policy that suits your needs. + For more information, see [Cluster setup](sessions.md#cluster-setup). -It's recommended to use a separated instance of Redis for sessions, that either never runs out of memory or uses an eviction policy that suits your needs. ## Conflict with roave/security-advisories diff --git a/docs/infrastructure_and_maintenance/background_tasks.md b/docs/infrastructure_and_maintenance/background_tasks.md index 2a21b5e924..932c0b23f4 100644 --- a/docs/infrastructure_and_maintenance/background_tasks.md +++ b/docs/infrastructure_and_maintenance/background_tasks.md @@ -12,7 +12,7 @@ To solve this, [[= product_name =]] provides a package called [[= product_name_b [[= product_name =]] sends messages (or commands) that represent the work to be done later. These messages are stored in a queue and picked up by a background worker, which ensures that resource-heavy tasks are executed at a convenient time, without putting excessive load on the system. -[[= product_name_base =]] Messenger supports multiple storage backends, such as Doctrine, Redis, and PostgreSQL, and gives developers the flexibility to create their own message handlers for custom use cases. +[[= product_name_base =]] Messenger supports multiple storage backends, such as Doctrine, Redis/Valkey, and PostgreSQL, and gives developers the flexibility to create their own message handlers for custom use cases. ## How it works @@ -23,7 +23,7 @@ The process works as follows: 1. A message PHP object is dispatched, for example, `ProductPriceReindex`. 2. The message is wrapped in an envelope, which may contain additional metadata, called stamps, for example, `DeduplicateStamp`. 3. The message is placed in the transport queue. -It can be a Doctrine table, a Redis queue, and so on. +It can be a Doctrine table, a Redis/Valkey queue, and so on. 4. A worker process continuously reads messages from the queue, pulls them into the default bus `ibexa.messenger.bus` and assigns them to the right handler. 5. A handler service processes the message (executes the command). You can register multiple handlers for different jobs. diff --git a/docs/infrastructure_and_maintenance/cache/persistence_cache.md b/docs/infrastructure_and_maintenance/cache/persistence_cache.md index 6bb4a2fafc..7772b83066 100644 --- a/docs/infrastructure_and_maintenance/cache/persistence_cache.md +++ b/docs/infrastructure_and_maintenance/cache/persistence_cache.md @@ -121,13 +121,16 @@ parameters: The only case where it's safe to increase these values is for dev environment with single concurrency on writes. In prod environment you should only consider reducing them if you have heavy concurrency writes. -### Redis +### Redis/Valkey [Redis](https://redis.io/), an in-memory data structure store, is one of the supported cache solutions for clustering. Redis is used via [Redis pecl extension](https://pecl.php.net/package/redis). See [Redis Cache Adapter in Symfony documentation]([[= symfony_doc =]]/components/cache/adapters/redis_adapter.html#configure-the-connection for information on how to connect to Redis. +[Valkey](https://valkey.io/), an alternative data structure store compatible with Redis, is also supported. +To set it up with [[= product_name =]], follow the same steps as for Redis. + #### Supported Adapters There are two Redis adapters available out of the box that fit different needs. diff --git a/docs/infrastructure_and_maintenance/clustering/clustering.md b/docs/infrastructure_and_maintenance/clustering/clustering.md index 57323c0338..5cc42fd375 100644 --- a/docs/infrastructure_and_maintenance/clustering/clustering.md +++ b/docs/infrastructure_and_maintenance/clustering/clustering.md @@ -13,12 +13,12 @@ The parts illustrate the different roles needed for a successful cluster setup. ![Server setup for clustering](server_setup.png) -The number of web servers, Redis, Solr, Varnish, Database, and NFS servers, but also whether some servers play several of these roles (typically running Redis across the web server), is up to you and your performance needs. +The number of web servers, Redis/Valkey, Solr, Varnish, Database, and NFS servers, but also whether some servers play several of these roles (typically running Redis/Valkey across the web server), is up to you and your performance needs. The minimal requirements are: - [Shared HTTP cache (using Varnish)](reverse_proxy.md#using-varnish-or-fastly) -- [Shared persistence cache](#shared-persistence-cache) and [sessions](#shared-sessions) (using Redis) +- [Shared persistence cache](#shared-persistence-cache) and [sessions](#shared-sessions) (using Redis/Valkey) - Shared database (using MySQL/MariaDB) - [Shared binary files](#shared-binary-files) (using NFS, or S3) @@ -34,14 +34,14 @@ It's also recommended to use: ### Shared persistence cache -Redis is the recommended cache solution for clustering. +Redis and Valkey are the recommended cache solutions for clustering. See [persistence cache documentation](persistence_cache.md#persistence-cache-configuration) on information on how to configure them. ### Shared sessions For a [cluster](clustering.md) setup you need to configure sessions to use a back end that is shared between web servers. -The main option out of the box in Symfony is the PHP Redis session handler, alternatively there is Symfony session handler for PDO (database). +The main option out of the box in Symfony is the PHP Redis session handler (also compatible with Valkey), alternatively there is Symfony session handler for PDO (database). To avoid concurrent access to session data from front-end nodes, if possible you should either: @@ -50,7 +50,7 @@ To avoid concurrent access to session data from front-end nodes, if possible you Session locking is available with `php-redis` (v4.2.0 and higher). -On [[= product_name_cloud =]] (and Upsun) Redis is preferred and supported. +On [[= product_name_cloud =]] (and Upsun) Redis and Valkey are preferred and supported. ### Shared binary files diff --git a/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md b/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md index 680c0b7ff8..1a180e7cff 100644 --- a/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md +++ b/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md @@ -116,7 +116,11 @@ In the following examples: - the same service is used to store both persistence cache and sessions - the session handler is set on Symfony side, not on PHP side -### Install Redis +### Install Redis or Valkey + +DDEV supports multiple Redis-compatible implementation, including Redis itself and Valkey. +You can switch between them using the `ddev redis-backend ` command. +For more information, see [Swappable Redis backends](https://github.com/ddev/ddev-redis?tab=readme-ov-file#swappable-redis-backends) in DDEV's `dddev-redis` add-on documentation. The following sequence of commands: @@ -137,7 +141,7 @@ ddev restart ddev php bin/console cache:clear ``` -You can now check whether Redis works. +You can now check whether the data store backend works. For example, the `ddev redis-cli MONITOR` command returns outputs, for example, `"SETEX" "ezp:`, `"MGET" "ezp:`, `"SETEX" "PHPREDIS_SESSION:`, or `"GET" "PHPREDIS_SESSION:`, while navigating into the website, in particular the back office. diff --git a/docs/infrastructure_and_maintenance/performance.md b/docs/infrastructure_and_maintenance/performance.md index e253198397..d8a72469eb 100644 --- a/docs/infrastructure_and_maintenance/performance.md +++ b/docs/infrastructure_and_maintenance/performance.md @@ -16,7 +16,7 @@ If you're in a hurry, the most important recommendations on this page are: - Dump optimized Composer autoload classmap - Use a full web (Nginx/Apache) server with vhost - Avoid shared filesystems for code (Docker for Mac/Win, VirtualBox/*, Vagrant, and more), or find ways to optimize or work around the issues. -- For clustering (mainly relevant for production/staging), reduce latency to Redis, use Varnish and [Solr](solr_overview.md). +- For clustering (mainly relevant for production/staging), reduce latency to Redis/Valkey, use Varnish and [Solr](solr_overview.md). ## Client @@ -31,7 +31,7 @@ In production setups: - Compared to the built-in Symfony Proxy in PHP Varnish is much faster and is able to queue up requests for the same fresh/invalidated resource. - With [ibexa/http-cache](https://github.com/ibexa/http-cache) support for xkey and grace Varnish provides more stable performance in read/write scenarios. - Set up [[= product_name =]] in [cluster mode](clustering.md) if you need to handle bigger spikes of traffic than a single server can manage. - - See [recommendation for Redis](#redis) and [Search](#search) below. + - See [recommendation for Redis-compatible data stores](#redis-compatible-data-stores) and [Search](#search) below. !!! note @@ -67,9 +67,9 @@ You can build them by running `yarn encore prod`, or by setting the environmenta - Keep Composer up to date. - Always dump optimized class map using `composer dump-autoload --optimize` or relevant flags on `composer install/update`. -### Redis +### Redis-compatible data stores -- Redis can in some cases perform better than filesystem cache even with a single server, as it offers better general performance for operations invalidating cache. +Redis and its alternatives, like Valkey, can in some cases perform better than filesystem cache even with a single server, as it offers better general performance for operations invalidating cache. - However, pure read performance is slower, especially if the next points aren't optimized. - With cache being on different node(s) than web server, make sure to try to tune latency between the two. @@ -77,8 +77,9 @@ You can build them by running `yarn encore prod`, or by setting the environmenta Check if your cloud provider has native service for Redis, as those might be better tuned. -- If you use Redis, make sure to tune it for in-memory cache usage. Its persistence feature isn't needed with cache and severely slows down execution time. - - [For use with sessions](sessions.md#cluster-setup) however, persistence can be a good fit if you want sessions to survive service interruptions. +When using Redis or Valkey, make sure to tune it for in-memory cache usage. +Its persistence feature isn't needed with cache and severely slows down execution time. +[For use with sessions](sessions.md#cluster-setup) however, persistence can be a good fit if you want sessions to survive service interruptions. For more information, see [Redis clustering](persistence_cache.md#redis-clustering). diff --git a/docs/infrastructure_and_maintenance/sessions.md b/docs/infrastructure_and_maintenance/sessions.md index bbcd588b1f..6c5702a973 100644 --- a/docs/infrastructure_and_maintenance/sessions.md +++ b/docs/infrastructure_and_maintenance/sessions.md @@ -9,7 +9,7 @@ It's further enhanced in [[= product_name =]] with support for SiteAccess-aware !!! note - Use of Redis (or experimentally PDO) as session handler is a requirement in a cluster setup, for details [see below](#cluster-setup). For an overview of the clustering feature see [Clustering](clustering.md). + Use of Redis, Valkey, or experimentally PDO as session handler is a requirement in a cluster setup, for details [see below](#cluster-setup). For an overview of the clustering feature see [Clustering](clustering.md). ## Configuration @@ -76,14 +76,16 @@ For a single server, the default file handler is preferred. See [shared sessions in the clustering guide](clustering.md#shared-sessions). -##### Handling sessions with Redis +##### Handling sessions with Redis and Valkey -To set up [[= product_name =]] using the [Redis](https://pecl.php.net/package/redis) you need to: +[[= product_name =]] supports storing sessions with [Redis](https://pecl.php.net/package/redis) or [Valkey](https://valkey.io/) data stores. + +To set it up, you need to: - [Configure the session save handler settings in `php.ini`](https://github.com/phpredis/phpredis/#php-session-handler) - Set `%ibexa.session.handler_id%` to `~` _(null)_ in `config/packages/ibexa.yaml` -Alternatively if you have needs to configure Redis servers dynamically: +Alternatively if you have needs to configure the servers dynamically: - Set `%ibexa.session.handler_id%` (or `SESSION_HANDLER_ID` env var) to `Ibexa\Bundle\Core\Session\Handler\NativeSessionHandler` - Set `%ibexa.session.save_path%` (or `SESSION_SAVE_PATH` env var) to [save_path config for Redis](https://github.com/phpredis/phpredis/#php-session-handler) @@ -97,10 +99,10 @@ If you're on `php-redis` v4.2.0 and higher, you can optionally tweak [`php-redis Ideally keep [persistence cache](persistence_cache.md) and session data separated: - Sessions can't risk getting [randomly evicted](https://redis.io/docs/latest/develop/reference/eviction/#eviction-policies) when you run out of memory for cache. -- You can't completely disable eviction either, as Redis then starts to refuse new entries once full, including new sessions. - - Either way, you should monitor your Redis instances and make sure you have enough memory set aside for active sessions/cache items. +- You can't completely disable eviction either, as the data store then starts to refuse new entries once full, including new sessions. + - Either way, you should monitor your data store instances and make sure you have enough memory set aside for active sessions/cache items. -If you want to make sure sessions survive Redis or server restarts, consider using a [persistent Redis](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) instance for sessions. +If you want to make sure sessions survive data store or server restarts, consider setting up [persistent storage](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) instance for sessions. ##### Alternative storing sessions in database by using PDO diff --git a/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md b/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md index 3445b41af6..feb032c3e7 100644 --- a/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md +++ b/docs/infrastructure_and_maintenance/support_and_maintenance_faq.md @@ -66,7 +66,7 @@ Useful commands: php bin/console cache:clear --env prod ``` -- clearing Redis cache +- clearing Redis/Valkey cache ```bash php bin/console cache:pool:clear cache.redis diff --git a/docs/snippets/page_block_cache_clear.md b/docs/snippets/page_block_cache_clear.md index 6823f7a239..9c833cd213 100644 --- a/docs/snippets/page_block_cache_clear.md +++ b/docs/snippets/page_block_cache_clear.md @@ -4,8 +4,8 @@ To clear the persistence cache run `./bin/console cache:pool:clear [cache-pool]` command. The default cache-pool is named `cache.tagaware.filesystem`. - The default cache-pool when running redis is named `cache.redis`. + The default cache-pool when running Redis or Valkey is named `cache.redis`. If you have customized the [persistence cache configuration](https://doc.ibexa.co/en/latest/infrastructure_and_maintenance/cache/persistence_cache/#what-is-cached), the name of your cache pool might be different. In prod mode, you also need to clear the symfony cache by running `./bin/console c:c`. - In dev mode, the Symfony cache is rebuilt automatically. \ No newline at end of file + In dev mode, the Symfony cache is rebuilt automatically. From 1dd08a24899cc5f21dcd4cf46457c9af193c08f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Fri, 16 Jan 2026 09:56:28 +0100 Subject: [PATCH 2/4] Apply suggestions from code review --- .../clustering/clustering_with_ddev.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md b/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md index 1a180e7cff..49e950feaf 100644 --- a/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md +++ b/docs/infrastructure_and_maintenance/clustering/clustering_with_ddev.md @@ -119,7 +119,8 @@ In the following examples: ### Install Redis or Valkey DDEV supports multiple Redis-compatible implementation, including Redis itself and Valkey. -You can switch between them using the `ddev redis-backend ` command. +You can switch between them using the `ddev redis-backend ` command after adding the `ddev/ddev-redis` add-on. +For example, you can switch to Valkey by running `ddev add-on get ddev/ddev-redis; ddev redis-backend valkey/valkey:9`. For more information, see [Swappable Redis backends](https://github.com/ddev/ddev-redis?tab=readme-ov-file#swappable-redis-backends) in DDEV's `dddev-redis` add-on documentation. The following sequence of commands: From aad85818173f50a79c761cabf5b3eb3837f2fc3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 20 Jan 2026 10:50:01 +0100 Subject: [PATCH 3/4] Apply suggestions from code review --- docs/infrastructure_and_maintenance/clustering/clustering.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/infrastructure_and_maintenance/clustering/clustering.md b/docs/infrastructure_and_maintenance/clustering/clustering.md index 5cc42fd375..4b7bbfa395 100644 --- a/docs/infrastructure_and_maintenance/clustering/clustering.md +++ b/docs/infrastructure_and_maintenance/clustering/clustering.md @@ -41,7 +41,8 @@ See [persistence cache documentation](persistence_cache.md#persistence-cache-con ### Shared sessions For a [cluster](clustering.md) setup you need to configure sessions to use a back end that is shared between web servers. -The main option out of the box in Symfony is the PHP Redis session handler (also compatible with Valkey), alternatively there is Symfony session handler for PDO (database). +The main option out of the box in Symfony is the PHP Redis session handler (also compatible with Valkey). +Alternatively, there is Symfony session handler for PDO (database). To avoid concurrent access to session data from front-end nodes, if possible you should either: From 5707a64542af970bea4553c0f5b595f1ad4afa95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 20 Jan 2026 11:00:39 +0100 Subject: [PATCH 4/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tomasz Dąbrowski <64841871+dabrt@users.noreply.github.com> --- docs/infrastructure_and_maintenance/performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/infrastructure_and_maintenance/performance.md b/docs/infrastructure_and_maintenance/performance.md index d8a72469eb..e8a46683e1 100644 --- a/docs/infrastructure_and_maintenance/performance.md +++ b/docs/infrastructure_and_maintenance/performance.md @@ -78,7 +78,7 @@ Redis and its alternatives, like Valkey, can in some cases perform better than f Check if your cloud provider has native service for Redis, as those might be better tuned. When using Redis or Valkey, make sure to tune it for in-memory cache usage. -Its persistence feature isn't needed with cache and severely slows down execution time. +The persistence feature isn't needed with cache and severely slows down execution time. [For use with sessions](sessions.md#cluster-setup) however, persistence can be a good fit if you want sessions to survive service interruptions. For more information, see [Redis clustering](persistence_cache.md#redis-clustering).