DocumentationCommerceConfiguration Guide

Configure Remote Storage

Last update: Wed Nov 29 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin
  • Developer

The Remote Storage module provides the option to store media files and schedule imports and exports in a persistent, remote storage container using a storage service, such as AWS S3. By default, the Adobe Commerce application stores media files in the same filesystem that contains the application. This is inefficient for complex, multi-server configurations, and can result in degraded performance when sharing resources. With the Remote Storage module, you can store media files in the pub/media directory and import/export files in the var directory of the remote object storage to take advantage of server-side image resizing.

INFO
Remote storage is available for Commerce version 2.4.2 and later only. See the 2.4.2 release notes.
INFO
The Remote storage module has limited support on Adobe Commerce on cloud infrastructure. Adobe cannot fully troubleshoot the third-party storage adapter service. See Configure remote storage for Commerce on Cloud infrastructure for guidance implementing remote storage for cloud projects.

schema image

Remote storage options

You can configure remote storage using the remote-storage option with the setup CLI command. The remote-storage option uses the following syntax:

--remote-storage-<parameter-name>="<parameter-value>"

The parameter-name refers to the specific remote storage parameter name. The following table lists the parameters available for configuring remote storage:

Command-line Parameter
Parameter name
Description
Default value
remote-storage-driver
driver
Adapter name
Possible values:
file: Disables remote storage and uses the local filesystem
aws-s3: Use the Amazon Simple Storage Service (Amazon S3)
none
remote-storage-bucket
bucket
Object storage or container name
none
remote-storage-prefix
prefix
Optional prefix (location inside of object storage)
empty
remote-storage-region
region
Region name
none
remote-storage-key
access key
Optional access key
empty
remote-storage-secret
secret key
Optional secret key
empty

Storage adapters

The default storage location is in the local filesystem. A storage adapter enables you to connect to a storage service and store your files anywhere. Commerce supports configuring the following storage services:

Enable remote storage

You can install remote storage during an Adobe Commerce installation or add remote storage to an existing Commerce instance. The following examples demonstrate each method using a set of remote-storage parameters with Commerce setup CLI commands. Minimally, you must supply the storage driver, bucket, and region.

  • Example: Install Commerce with remote storage

    code language-bash 
    bin/magento setup:install --remote-storage-driver="aws-s3" --remote-storage-bucket="myBucket" --remote-storage-region="us-east-1"

  • Example: Enable remote storage on existing Commerce

    code language-bash 
    bin/magento setup:config:set --remote-storage-driver="aws-s3" --remote-storage-bucket="myBucket" --remote-storage-region="us-east-1"
TIP
For Adobe Commerce on cloud infrastructure, see Configure remote storage for Commerce on Cloud infrastructure.

Limitations

You cannot have both remote storage and database storage enabled at the same time. Disable database storage if you are using remote storage.

bin/magento config:set system/media_storage_configuration/media_database 0

Enabling remote storage might affect your established development experience. For example, certain PHP file functions might not work as expected. The usage of Commerce Framework for file operations must be enforced.

The list of prohibited PHP native functions is available in magento-coding-standard repository.

Migrate content

After you enable remote storage for a specific adapter, you can use the CLI to migrate existing media files to the remote storage.

./magento2ce/bin/magento remote-storage:sync
INFO
The sync command only migrates files in the pub/media directory, not the import/export files in the var directory. See Scheduled Import/Export in the Commerce 2.4 User Guide.
recommendation-more-help
386822bd-e32c-40a8-81c2-ed90ad1e198c