Skip to content

Add Dragonfly cache configuration documentation #167

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vyavdoshenko wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Dragonfly cache configuration documentation #167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions help/configuration/TOC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
135 changes: 135 additions & 0 deletions help/configuration/cache/config-dragonfly.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
204 changes: 204 additions & 0 deletions help/configuration/cache/dragonfly-pg-cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<Commerce-install-dir>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-<parameter>=<value>...
```

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-<parameter>=<value>` 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.<br><br>**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-<parameter>=<value>...
```

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-<parameter>=<value>` 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.<br/>**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 `<Commerce-install-dir>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.
Loading