From f24c7acc962735a718c0fc93bb73f8e3c0fec413 Mon Sep 17 00:00:00 2001 From: Volodymyr Yavdoshenko Date: Mon, 12 Jan 2026 19:45:06 +0200 Subject: [PATCH] fix: Dragonfly cache docs were added --- help/configuration/TOC.md | 4 + help/configuration/cache/config-dragonfly.md | 135 ++++++++++++ .../configuration/cache/dragonfly-pg-cache.md | 204 ++++++++++++++++++ help/configuration/cache/dragonfly-session.md | 118 ++++++++++ 4 files changed, 461 insertions(+) create mode 100644 help/configuration/cache/config-dragonfly.md create mode 100644 help/configuration/cache/dragonfly-pg-cache.md create mode 100644 help/configuration/cache/dragonfly-session.md diff --git a/help/configuration/TOC.md b/help/configuration/TOC.md index 764b9dd6d..179fe5922 100644 --- a/help/configuration/TOC.md +++ b/help/configuration/TOC.md @@ -40,6 +40,10 @@ feature: Configuration + [Configure Valkey](cache/config-valkey.md) + [Use Valkey for default cache](cache/valkey-pg-cache.md) + [Use Valkey for session storage](cache/valkey-session.md) + + Dragonfly {#dragonfly} + + [Configure Dragonfly](cache/config-dragonfly.md) + + [Use Dragonfly for default cache](cache/dragonfly-pg-cache.md) + + [Use Dragonfly for session storage](cache/dragonfly-session.md) + Varnish {#varnish} + [Varnish overview](cache/config-varnish.md) + [Install Varnish](cache/config-varnish-install.md) diff --git a/help/configuration/cache/config-dragonfly.md b/help/configuration/cache/config-dragonfly.md new file mode 100644 index 000000000..5380027d9 --- /dev/null +++ b/help/configuration/cache/config-dragonfly.md @@ -0,0 +1,135 @@ +--- +title: Configure Dragonfly +description: Learn how to configure Dragonfly caching for Adobe Commerce performance optimization. Discover features, setup steps, and configuration best practices. +feature: Configuration, Cache +--- +# Configure Dragonfly + +Dragonfly is a modern in-memory datastore that is fully compatible with Redis and Memcached APIs. It offers significant performance improvements through its multi-threaded, shared-nothing architecture while requiring no code changes for existing Redis integrations. + +Dragonfly features include: + +- Full Redis API compatibility +- PHP session storage +- Tag-based cache cleanup without `foreach` loops +- On-disk saves and master/replica replication +- Multi-threaded architecture for improved performance + +## Install Dragonfly + +To install and configure the Dragonfly software, consult the following resources: + +- [Dragonfly GitHub releases](https://github.com/dragonflydb/dragonfly/releases) +- [Dragonfly quick start](https://www.dragonflydb.io/docs/getting-started) +- [Dragonfly documentation](https://www.dragonflydb.io/docs) + +### Docker installation + +The quickest way to get started with Dragonfly is using Docker. + +**Linux:** + +```bash +docker run --network=host --ulimit memlock=-1 docker.dragonflydb.io/dragonflydb/dragonfly +``` + +**macOS and Windows:** + +```bash +docker run -p 6379:6379 --ulimit memlock=-1 docker.dragonflydb.io/dragonflydb/dragonfly +``` + +### Binary installation + +1. Download the appropriate binary from [Dragonfly releases](https://github.com/dragonflydb/dragonfly/releases). + +1. Extract and rename the binary: + + ```bash + tar -xzf dragonfly-*.tar.gz + mv dragonfly-* dragonfly + ``` + +1. Start Dragonfly: + + ```bash + ./dragonfly --logtostderr + ``` + +## Set up Dragonfly configuration + +Dragonfly uses command-line flags for configuration. You can also use a configuration file with the `--flagfile` option. + +To optimize the Dragonfly instance for your requirements, you get best results by using a dedicated instance for each session, Commerce cache, and FPC. + +Adobe recommends enabling persistence for sessions using snapshot-based persistence. Dragonfly supports point-in-time snapshots that store the complete database in a dump file. + +- **Snapshot persistence** stores the complete database in a dump file. You can configure automatic snapshots using the `--snapshot_cron` flag or manual snapshots using the `BGSAVE` command. + +For the cache instance, set up the instance so that it is large enough to store your entire Commerce cache. Size requirements depend on different factors like the number of products and store views. As a starting point, you can use the size of the cache folder on your file system. For example, if the `var/cache` folder on your file system is 5 GB, set up your Dragonfly instance with at least 5 GB to start. Persistence is not required for the cache instance because the Commerce cache can be restored. + +### Common configuration flags + +| Flag | Default | Description | +|------|---------|-------------| +| `--port` | `6379` | Server port for client connections | +| `--bind` | (all interfaces) | Bind address | +| `--requirepass` | (empty) | Password for AUTH authentication | +| `--maxmemory` | `0` (automatic) | Maximum memory limit in bytes | +| `--dbnum` | `16` | Number of databases | +| `--dir` | (current) | Working directory for snapshots | +| `--dbfilename` | `dump-{timestamp}` | Snapshot filename | +| `--snapshot_cron` | (disabled) | Cron expression for automatic snapshots | +| `--proactor_threads` | `0` (auto) | Number of I/O threads | +| `--cache_mode` | `false` | Enable cache mode with automatic eviction | + +### Example configuration + +Create a configuration file `/etc/dragonfly/dragonfly.conf`: + +```ini +--port=6379 +--bind=127.0.0.1 +--requirepass=your_password +--maxmemory=4294967296 +--dir=/var/lib/dragonfly +--dbfilename=dump +--snapshot_cron=0 */6 * * * +--cache_mode=true +``` + +Start Dragonfly with the configuration file: + +```bash +dragonfly --flagfile=/etc/dragonfly/dragonfly.conf +``` + +## Verify Dragonfly connection + +To verify that Dragonfly and Commerce are working together properly, log in to the server running Dragonfly, open a terminal, and use the Redis CLI commands. Dragonfly is fully compatible with `redis-cli`. + +### Ping command + +```bash +redis-cli ping +``` + +The expected response is: `PONG` + +### Monitor command + +```bash +redis-cli monitor +``` + +This displays all commands processed by the server in real-time. + +### Connection test with authentication + +If you configured a password: + +```bash +redis-cli -a your_password ping +``` + +If the command succeeds, Dragonfly is set up properly. diff --git a/help/configuration/cache/dragonfly-pg-cache.md b/help/configuration/cache/dragonfly-pg-cache.md new file mode 100644 index 000000000..d0a32acc3 --- /dev/null +++ b/help/configuration/cache/dragonfly-pg-cache.md @@ -0,0 +1,204 @@ +--- +title: Use Dragonfly for default cache +description: Learn how to configure Dragonfly as the default cache for Adobe Commerce. Discover command-line setup, configuration options, and validation techniques. +feature: Configuration, Cache +--- + +# Use Dragonfly for default cache + +Commerce provides command-line options to configure the default and page caching using Dragonfly. Because Dragonfly is fully compatible with Redis, you can use the Redis backend configuration to connect to Dragonfly. Although you can configure caching by editing the `app/etc/env.php` file, using the command line is the recommended method, especially for initial configurations. The command line provides validation, ensuring the configuration is syntactically correct. + +You must [install Dragonfly](config-dragonfly.md#install-dragonfly) before continuing. + +## Configure Dragonfly default caching + +Run the `setup:config:set` command and specify parameters for Redis backend configuration. Dragonfly accepts Redis connections without modification. + +```bash +bin/magento setup:config:set --cache-backend=redis --cache-backend-redis-=... +``` + +With the following parameters: + +- `--cache-backend=redis` enables the Redis backend, which is compatible with Dragonfly. If this feature has already been enabled, omit this parameter. + +- `--cache-backend-redis-=` is a list of key-value pairs that configure the default caching: + +| Command-line parameter | Value | Meaning | Default value | +|---|---|---|---| +| `cache-backend-redis-server` | server | Fully qualified hostname, IP address, or an absolute path to a UNIX socket. The default value of `127.0.0.1` indicates that Dragonfly is installed on the Commerce server. | `127.0.0.1` | +| `cache-backend-redis-port` | port | Dragonfly server listen port | `6379` | +| `cache-backend-redis-db` | database | Required if you use Dragonfly for both the default and full-page cache. You must specify the database number of one of the caches; the other cache uses `0` by default.

**Important**: If you use Dragonfly for more than one type of caching, the database numbers must be different. Adobe recommends that you assign the default caching database number to `0`, the page-caching database number to `1`, and the session storage database number to `2`. | `0` | +| `cache-backend-redis-password` | password | Configuring a Dragonfly password enables one of its built-in security features: the `auth` command, which requires clients to authenticate to access the database. Configure the password using the `--requirepass` flag when starting Dragonfly. | | + +### Example command + +The following example enables Dragonfly default caching, sets the host to `127.0.0.1`, and assigns the database number to `0`. Dragonfly uses default values for all other parameters. + +```bash +bin/magento setup:config:set --cache-backend=redis --cache-backend-redis-server=127.0.0.1 --cache-backend-redis-db=0 +``` + +## Configure page caching + +To configure Dragonfly page caching on Commerce, run the `setup:config:set` command with additional parameters. + +```bash +bin/magento setup:config:set --page-cache=redis --page-cache-redis-=... +``` + +With the following parameters: + +- `--page-cache=redis` enables Redis page caching, which is compatible with Dragonfly. If this feature has already been enabled, omit this parameter. + +- `--page-cache-redis-=` is a list of key-and-value pairs that configure page caching: + +| Command-line parameter | Value | Meaning | Default value | +|---|---|---|---| +| `page-cache-redis-server` | server | Fully qualified hostname, IP address, or an absolute path to a UNIX socket. The default value of `127.0.0.1` indicates that Dragonfly is installed on the Commerce server. | `127.0.0.1` | +| `page-cache-redis-port` | port | Dragonfly server listen port | `6379` | +| `page-cache-redis-db` | database | Required if you use Dragonfly for both default and full-page cache. You must specify the database number of one of the caches; the other cache uses `0` by default.
**Important**: If you use Dragonfly for more than one type of caching, the database numbers must be different. It is recommended that you assign the default caching database number to `0`, the page-caching database number to `1`, and the session storage database number to `2`. | `0` | +| `page-cache-redis-password` | password | Configuring a Dragonfly password enables one of its built-in security features: the `auth` command, which requires clients to authenticate to access the database. Configure the password using the `--requirepass` flag when starting Dragonfly. | | + +### Example command + +The following example enables Dragonfly page caching, sets the host to `127.0.0.1`, and assigns the database number to `1`. All other parameters are set to the default value. + +```bash +bin/magento setup:config:set --page-cache=redis --page-cache-redis-server=127.0.0.1 --page-cache-redis-db=1 +``` + +## Results + +As a result of the two example commands, Commerce adds lines similar to the following to `app/etc/env.php`: + +```php +'cache' => [ + 'frontend' => [ + 'default' => [ + 'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis', + 'backend_options' => [ + 'server' => '127.0.0.1', + 'database' => '0', + 'port' => '6379' + ], + ], + 'page_cache' => [ + 'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis', + 'backend_options' => [ + 'server' => '127.0.0.1', + 'port' => '6379', + 'database' => '1', + 'compress_data' => '0' + ] + ] + ] +], +``` + +## Dragonfly preload feature + +Since Commerce stores configuration data in the cache, you can preload data that is reused between pages. To find keys that must be preloaded, analyze data that is transferred from Dragonfly to Commerce. Adobe suggests preloading data that is loaded on every page, such as `SYSTEM_DEFAULT`, `EAV_ENTITY_TYPES`, and `DB_IS_UP_TO_DATE`. + +Dragonfly uses the `pipeline` to composite load requests. Keys should include the database prefix; for example, if database prefix is `061_`, the preload key looks like: `061_SYSTEM_DEFAULT` + +```php +'cache' => [ + 'frontend' => [ + 'default' => [ + 'id_prefix' => '061_', + 'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis', + 'backend_options' => [ + 'server' => 'dragonfly', + 'database' => '0', + 'port' => '6379', + 'password' => '', + 'compress_data' => '1', + 'compression_lib' => '', + 'preload_keys' => [ + '061_EAV_ENTITY_TYPES', + '061_GLOBAL_PLUGIN_LIST', + '061_DB_IS_UP_TO_DATE', + '061_SYSTEM_DEFAULT', + ], + ] + ], + 'page_cache' => [ + 'id_prefix' => '061_' + ] + ] +] +``` + +When using the preload feature with an L2 cache, you must add the `:hash` suffix to your keys. The L2 cache transfers only the hash of the data, not the actual data. + +```php +'preload_keys' => [ + '061_EAV_ENTITY_TYPES:hash', + '061_GLOBAL_PLUGIN_LIST:hash', + '061_DB_IS_UP_TO_DATE:hash', + '061_SYSTEM_DEFAULT:hash', +], +``` + +## Parallel generation + +Starting with the Commerce 2.4.0 release, Adobe introduced the `allow_parallel_generation` option for users who want to eliminate waitings for locks. +It is disabled by default, and Adobe recommends disabling it until you have excessive configurations and/or blocks. + +**To enable parallel generation**: + +```bash +bin/magento setup:config:set --allow-parallel-generation +``` + +Since it is a flag, you cannot disable it with a command. You must manually set the configuration value to `false`: + +```php + 'cache' => [ + 'frontend' => [ + 'default' => [ + 'id_prefix' => 'b0b_', + 'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis', + 'backend_options' => [ + 'server' => 'dragonfly', + 'database' => '0', + 'port' => '6379', + 'password' => '', + 'compress_data' => '1', + 'compression_lib' => '' + ] + ], + 'page_cache' => [ + 'id_prefix' => 'b0b_' + ] + ], + 'allow_parallel_generation' => false + ], +``` + +## Verify Dragonfly connection + +To verify that Dragonfly and Commerce are working together properly, log in to the server that runs Dragonfly, open a terminal, and use the `redis-cli monitor` command or the `redis-cli ping` command. + +### Monitor command + +```bash +redis-cli monitor +``` + +This displays all commands processed by the server in real-time, allowing you to verify that Commerce is communicating with Dragonfly. + +### Ping command + +```bash +redis-cli ping +``` + +The expected response is: `PONG` + +If both commands succeeded, Dragonfly is set up properly. + +### Inspecting compressed data + +To inspect compressed session data and the page cache, the [RESP.app](https://resp.app/) supports automatic decompression of Commerce 2 session and page cache and displays PHP session data in a human-readable format. diff --git a/help/configuration/cache/dragonfly-session.md b/help/configuration/cache/dragonfly-session.md new file mode 100644 index 000000000..f8feecf98 --- /dev/null +++ b/help/configuration/cache/dragonfly-session.md @@ -0,0 +1,118 @@ +--- +title: Use Dragonfly for session storage +description: Learn how to configure Dragonfly for session storage in Adobe Commerce. Discover setup steps, configuration options, and performance optimization techniques. +feature: Configuration, Cache +--- + +# Use Dragonfly for session storage + +>[!IMPORTANT] +> +>You must [install Dragonfly](config-dragonfly.md#install-dragonfly) before continuing. + +Adobe Commerce provides command-line options to configure session storage using Dragonfly. Because Dragonfly is fully compatible with Redis, you can use the Redis session configuration. + +Run the `setup:config:set` command and specify Redis-specific parameters. + +```bash +bin/magento setup:config:set --session-save=redis --session-save-redis-=... +``` + +With the following parameters: + +- `--session-save=redis` enables Redis session storage, which is compatible with Dragonfly. If this feature is already enabled, omit this parameter. + +- `--session-save-redis-=` is a list of parameter/value pairs that configure session storage: + +| Command-line Parameter | Parameter name | Meaning | Default value | +|---|---|---|---| +| session-save-redis-host | host | Fully qualified hostname, IP address, or absolute path if using UNIX sockets. | localhost | +| session-save-redis-port | port | Dragonfly server listen port. | 6379 | +| session-save-redis-password | password | Specifies a password if your Dragonfly server requires authentication. | empty | +| session-save-redis-timeout | timeout | Connection timeout, in seconds. | 2.5 | +| session-save-redis-persistent-id | persistent_identifier | Unique string to enable persistent connections (for example, sess-db0).
[Known issues with phpredis and php-fpm](https://github.com/phpredis/phpredis/issues/70). | | +| session-save-redis-db | database | Unique Dragonfly database number, which is recommended to protect against data loss.

**Important**: If you use Dragonfly for more than one type of caching, the database numbers must be different. It is recommended that you assign the default caching database number to `0`, the page-caching database number to `1`, and the session storage database number to `2`. | 0 | +| session-save-redis-compression-threshold | compression_threshold | Set to `0` to disable compression (recommended when `suhosin.session.encrypt = On`). | 2048 | +| session-save-redis-compression-lib | compression_library | Options: gzip, lzf, lz4 or snappy. | gzip | +| session-save-redis-log-level | log_level | Set to any of the following, listed in order from least verbose to most verbose:
  • 0 (emergency: only the most severe errors)
  • 1 (alert: immediate action required)
  • 2 (critical: application component unavailable)
  • 3 (error: runtime errors, not critical but must be monitored)
  • 4 (warning: additional information, recommended)
  • 5 (notice: normal but significant condition)
  • 6 (info: informational messages)
  • 7 (debug: the most information for development or testing only)
| 1 | +| session-save-redis-max-concurrency | max_concurrency | Maximum number of processes that can wait for a lock on one session. For large production clusters, set this to at least 10% of the number of PHP processes. | 6 | +| session-save-redis-break-after-frontend | break_after_frontend | Number of seconds to wait before trying to break the lock for frontend (that is, storefront) session. | 5 | +| session-save-redis-break-after-adminhtml | break_after_adminhtml | Number of seconds to wait before trying to break the lock for an adminhtml (that is, Admin) session. | 30 | +| session-save-redis-first-lifetime | first_lifetime | Lifetime, in seconds, of session for non-bots on the first write, or use `0` to disable. | 600 | +| session-save-redis-bot-first-lifetime | bot_first_lifetime | Lifetime, in seconds, of session for bots on the first write, or use `0` to disable. | 60 | +| session-save-redis-bot-lifetime | bot_lifetime | Lifetime, in seconds, of session for bots on subsequent writes, or use `0` to disable. | 7200 | +| session-save-redis-disable-locking | disable_locking | Disable session locking entirely. | 0 (false) | +| session-save-redis-min-lifetime | min_lifetime | Minimum session lifetime, in seconds. | 60 | +| session-save-redis-max-lifetime | max_lifetime | Maximum session lifetime, in seconds. | 2592000 (720 hours) | + +>[!NOTE] +> +>Redis Sentinel parameters (`sentinel_master`, `sentinel_servers`, etc.) are not applicable for Dragonfly. Dragonfly uses its own replication mechanism. See the [Dragonfly replication documentation](https://www.dragonflydb.io/docs/managing-dragonfly/replication) for high availability configuration. + +## Example + +The following example sets Dragonfly as the session data store, sets the host to `127.0.0.1`, sets the log level to `4`, and sets the database number to `2`. All other parameters are set to the default value. + +```bash +bin/magento setup:config:set --session-save=redis --session-save-redis-host=127.0.0.1 --session-save-redis-log-level=4 --session-save-redis-db=2 +``` + +### Result + +Commerce adds lines similar to the following to `app/etc/env.php`: + +```php +'session' => [ + 'save' => 'redis', + 'redis' => [ + 'host' => '127.0.0.1', + 'port' => '6379', + 'password' => '', + 'timeout' => '2.5', + 'persistent_identifier' => '', + 'database' => '2', + 'compression_threshold' => '2048', + 'compression_library' => 'gzip', + 'log_level' => '4', + 'max_concurrency' => '6', + 'break_after_frontend' => '5', + 'break_after_adminhtml' => '30', + 'first_lifetime' => '600', + 'bot_first_lifetime' => '60', + 'bot_lifetime' => '7200', + 'disable_locking' => '0', + 'min_lifetime' => '60', + 'max_lifetime' => '2592000', + ], +], +``` + +>[!INFO] +> +>TTL for session records uses the value for Cookie Lifetime, which is configured in the Admin. If Cookie Lifetime is set to `0` (the default is `3600`), then sessions expire in the number of seconds specified in min_lifetime (the default is `60`). This discrepancy is due to differences in how Dragonfly and session cookies interpret a lifetime value of `0`. If that behavior is not desired, increase the value of min_lifetime. + +## Verify Dragonfly connection + +To verify that Dragonfly and Commerce are working together properly, log in to the server where Dragonfly is running, open a terminal, and use the `redis-cli monitor` command or the `redis-cli ping` command. + +### Monitor command + +```bash +redis-cli monitor +``` + +This displays all commands processed by the server in real-time, allowing you to verify that Commerce is communicating with Dragonfly. + +### Ping command + +```bash +redis-cli ping +``` + +The expected response is: `PONG`. + +If both commands succeeded, Dragonfly is set up properly. + +### Inspecting compressed data + +To inspect compressed session data and the page cache, the [RESP.app](https://resp.app/) supports automatic decompression of Commerce 2 session and page cache and displays PHP session data in a human-readable format.