Store files on S3, Google Cloud or Azure: Maho storage mounts
Media, customer uploads, downloads, sitemaps and feeds go through named mounts: local.xml points one at a bucket and several web nodes work with no shared disk.
Two web nodes in front of a store, and the first problem is not load: it is that an image upload lands on one node and the other cannot see it. The classic answer is a network filesystem, which brings permissions, locks and a latency you feel on every page. 26.11.0 takes another route: the files the nodes must share go through named storage mounts, and each one can live on a bucket.
What a mount holds
Behind each name there is a Flysystem filesystem. In the default configuration what sits underneath is a local folder, so a single server store configures nothing and finds the same paths it had before.
| Mount | Local folder | Contents |
|---|---|---|
media |
public/media |
product, category, blog and CMS images, feed files |
custom_options |
public/media/custom_options |
files a customer uploads with a product custom option |
downloadable |
public/media/downloadable |
purchased files and their samples |
customer |
public/media/customer |
files uploaded with a customer attribute |
customer_address |
public/media/customer_address |
files uploaded with an address attribute |
exports |
var/export |
Dataflow export files |
imports |
var/import |
Dataflow import files and profile uploads |
feeds |
var/feedmanager |
work files of a feed the admin generates in batches |
sitemaps |
public |
the sitemap files |
importexport_exports |
var/importexport/export |
files of System > Import/Export > Export, deleted after 7 days |
Cache, sessions, logs, var/tmp and locks stay outside: the nodes do not need to
share them, and cache and sessions belong on Redis. Each node keeps its own logs and
temporary files, and on more than one node the lock backend should be set to db.
What to install
Maho ships the local adapter only. A bucket needs the package of the service:
| Service | <type> |
Package |
|---|---|---|
| Amazon S3 and compatible (MinIO, Cloudflare R2, Spaces) | s3 |
league/flysystem-aws-s3-v3 |
| Google Cloud Storage | gcs |
league/flysystem-google-cloud-storage |
| Azure Blob Storage | azure |
azure-oss/storage-blob-flysystem |
composer require league/flysystem-aws-s3-v3
Azure uses the azure-oss package because Microsoft retired its Azure Storage PHP
libraries in March 2024.
Configuring a mount
Add a <storage> block to app/etc/local.xml: a mount declared there replaces the
adapter of the mount with the same name.
<config>
<global>
<storage>
<mounts>
<media>
<adapter>
<type>s3</type>
<bucket>my-store-media</bucket>
<prefix>media</prefix>
<region>eu-west-1</region>
<key>AKIA...</key>
<secret>...</secret>
</adapter>
</media>
</mounts>
</storage>
</global>
</config>
The other mounts stay on the disk, and move one at a time: repeat the block with
their name. A compatible store such as MinIO also wants the <endpoint> element and
the use_path_style_endpoint option set to 1.
The elements that matter:
<visibility>,publicorprivate, is what Maho sets on each write. Do not set it on an S3 bucket with ACLs disabled, which is the default for new buckets: give read access with a bucket policy instead.gcswantsbucketand acceptsprefix,project_idandkey_file, the path to a service account JSON file. Withoutkey_filethe Google client finds the credentials itself.azurewantscontainerandconnection_string, and acceptsprefixandpublic_container.
One bucket or one prefix per mount. Only media holds public files.
Media URLs and a CDN
Media URLs come from the Base Media URL of the store even when the mount is on a bucket, so serving media from a CDN is the same move you make with a local disk:
./maho config:set web/unsecure/base_media_url https://cdn.example.com/media/
./maho config:set web/secure/base_media_url https://cdn.example.com/media/
From then on every media URL points at the CDN: product images, blog and category
images, the logo, {{media url=...}} directives and the images of extensions.
Private files
custom_options, downloadable, customer, customer_address and
importexport_exports hold files only Maho should serve. A private mount does not
follow the media mount: when media moves to a bucket, they move too, or their
files stay on the disk of the node that received them. The right place is a bucket
that allows no public read, never the media bucket.
<downloadable>
<adapter>
<type>s3</type>
<bucket>my-store-private</bucket>
<prefix>downloadable</prefix>
<region>eu-west-1</region>
</adapter>
</downloadable>
Two commands check it: a private file must answer 403 and a product image 200.
# the private file must not be readable directly
curl -I https://my-store-private.s3.eu-west-1.amazonaws.com/downloadable/files/links/a/b/file.zip
# the product image must be
curl -I https://my-store-media.s3.eu-west-1.amazonaws.com/media/catalog/product/a/b/image.jpg
A customer downloads a purchased file through Maho. When the mount can sign a URL, Maho redirects to a signed URL that expires after 60 seconds; otherwise it streams the file.
Resized images
Maho creates the resized files of product, category, blog and swatch images at the
widths of the theme image slots before a page links them, and stores them on the
media mount under cache/, for example catalog/product/cache/. A save in the
admin or through the API creates the files of the new images after the database
commit. An import queues them on the image queue, in the slow pool, and a resize
that fails goes back to the queue.
Three things to keep in mind:
- on a local disk the web server sends a request for a missing file to Maho,
which creates it and returns it.
.htaccessand Caddy already do it, nginx needs its own rule; - on a bucket a missing file never reaches Maho by itself: the queue and
storage:image:resizerepair it, or the CDN is configured to send misses below/media/<folder>/cache/to Maho. S3 answers403rather than404when the bucket policy does not allow listing, so both codes need handling; - when the theme or the image settings change the URLs change at once, and the
image_settings_checkcron looks for missing files every 15 minutes. On a bucket with no CDN rule, runstorage:image:resizein the deploy that changes the slots.
The three commands
# show what it would copy, and copy nothing
./maho storage:migrate --dry-run
# copy the local folders to the buckets local.xml configures
./maho storage:migrate --jobs 16
# create the missing resized files ahead of time
./maho storage:image:resize
# delete the sizes no template uses
./maho storage:image:clean
storage:migrate takes the mount names to migrate, --dry-run, --exclude to skip
a folder, --jobs for parallelism, which is 16 by default towards a bucket, and
--include-cache to copy the caches Maho rebuilds anyway. storage:image:resize
takes --entity to stay on product, category or blog, and --jobs.
When it is worth it
A mount pays off on a single server too, and the most concrete reason is space: a catalog with a few thousand images fills the disk of the host, and that disk is paid for even when it stops growing. With the media on an S3 or compatible bucket the images take no disk on the server, the disk stays for cache, sessions, logs and the database, and the storage serves the files through its public URL or through the CDN in front of it, without going through the web server of the store.
It also pays off when there is more than one node, when a deploy has to be able to
start with an empty public/media, or when a CDN should serve the media. A single
server with enough room can stay unconfigured, and finds the paths it had before.
If the store has to leave a single machine, MageMEGA managed hosting runs Maho on FrankenPHP with the deploy from the same repository, and the bucket is configured as on any other server.
What leaves the core
The old database media storage had no admin setting left, so it is gone with its
Mage_Core_Model_File_Storage_* classes and its config nodes, except
image_file_type and image_quality. The tables stay in the database. A module
that read those paths now finds a method that returns a path on the mount, such as
getBase*StoragePath() in place of getBase*Path() on downloadable links and
samples.
Text prepared with the help of AI and checked against the source before publication. It can still contain mistakes: if you find one, report it.Read the manifesto
Source: MahoCommerce/maho#1472
Does your store still sell?
Tell us where you are starting from: we reply with a first assessment, no strings attached.
Ask for the store assessment