Vai al contenuto

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>, public or private, 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.
  • gcs wants bucket and accepts prefix, project_id and key_file, the path to a service account JSON file. Without key_file the Google client finds the credentials itself.
  • azure wants container and connection_string, and accepts prefix and public_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. .htaccess and 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:resize repair it, or the CDN is configured to send misses below /media/<folder>/cache/ to Maho. S3 answers 403 rather than 404 when 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_check cron looks for missing files every 15 minutes. On a bucket with no CDN rule, run storage:image:resize in 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