Configure AWS S3 bucket for remote storage

Last update: 2023-05-16
  • Created for:
  • Experienced

The Amazon Simple Storage Service (Amazon S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance. The AWS S3 service uses buckets, or containers, for data storage. This configuration requires you to create a private bucket. For Adobe Commerce on cloud infrastructure, see Configure remote storage for Commerce on Cloud infrastructure.


Adobe highly discourages the use of public buckets because it poses a serious security risk.

To enable remote storage with the AWS S3 adapter:

  1. Log in to your Amazon S3 dashboard and create a private bucket.

  2. Set up AWS IAM roles. Alternatively, generate access and secret keys.

  3. Disable the default database storage.

    bin/magento config:set system/media_storage_configuration/media_database 0
  4. Configure Commerce to use the private bucket. See Remote storage options for a full list of parameters.

    bin/magento setup:config:set --remote-storage-driver="aws-s3" --remote-storage-bucket="<bucket-name>" --remote-storage-region="<region-name>" --remote-storage-prefix="<optional-prefix>" --remote-storage-key=<optional-access-key> --remote-storage-secret=<optional-secret-key> -n
  5. Synchronize media files with remote storage.

    bin/magento remote-storage:sync

Configure Nginx

Nginx requires additional configuration to perform Authentication with the proxy_pass directive. Add the following proxy information to the nginx.conf file:


location ~* \.(ico|jpg|jpeg|png|gif|svg|js|css|swf|eot|ttf|otf|woff|woff2)$ {
    # Proxying to AWS S3 storage.
    set $bucket "<s3-bucket-name>";
    proxy_pass_request_body off;
    proxy_pass_request_headers off;
    proxy_intercept_errors on;
    proxy_hide_header "x-amz-id-2";
    proxy_hide_header "x-amz-request-id";
    proxy_hide_header "x-amz-storage-class";
    proxy_hide_header "Set-Cookie";
    proxy_ignore_headers "Set-Cookie";


If you use access and secret keys instead of AWS IAM roles, you must include the ngx_aws_auth Nginx module.


The S3 integration relies on the ability to generate and store cached images on the local file system. Therefore, folder permissions for pub/media and similar directories are the same for S3 as they are when using local storage.

File Operations

It is highly recommended that you use Commerce file adapter methods in your coding or extension development, regardless of the file storage type. When using S3 for storage, do not use native PHP file I/O operations, such as copy, rename, or file_put_contents, because S3 files are not located within the file system. See DriverInterface.php for code examples.

On this page