Find some ideas related to project architecture and the possible solutions for extracting static files as an external filesystem service for Magento 2.

Take this architecture documentation page as a guideline, and not as a part provided by these extensions.


  • This project is under active development phase, and there are plans for a bunch of new features or Magento 2 Community platform refactoring. You can check there plans on Project Roadmap.
  • Feel free to create new issues for feature requests, new ideas, and improvements or bugs related to these extensions: On GitHub
  • Subscribe to the mailing list


Before going deeper into the development details, please note that this module for Magento 2 is extending core module interfaces, keeping in mind the backward compatibility and keeping the breaking changes as low as possible.

Software architecture

File storage architecture for Magento 2

Upload images in the admin area

Uploading files from user interfaces or programmatically should be compatible with any customization as log as is using the Magento standard interfaces and Filesystem object to obtain it.

Nevertheless, the business logic is not changed, and cloud storage services are integrated using a core filesystem interface.

Upload image for product or CMS blocks


Uploading product attachments for downloadable products work just like uploading the product image shown in the above schema.

Resized image delivery

Resizing images could be performed on the Magento /media path, similar to the case when files were on disk. The difference is that, for directories mapped to cloud storage service, files will be loaded using the proper driver for the service.

A better way could be to have this path behind a reverse proxy configuration. A sample configuration is provided for the Nginx server.

The proxy can be implemented as follow:

  • try to deliver the file from the storage system by a proxy_pass call
  • when missing try to process the image using the Magento standard path /media/*
  • save the result to the storage system
  • send the file to user
Upload image for product or CMS blocks

Frontend image delivery for original images

Original images could be delivered directly from the storage system, or the CDN in front of it, by configuring the base media URL in admin configuration under Store -> Configuration.

There is a known limitation here for using multiple storage containers for mapping existing media directory because the URL for cms blocks and page is constructed using the same base URL as product images. This means, for now, the core media directory could be mapped to only one remote directory, CMS images and the product page should reside in the same cloud storage container.