Adobe Commerce Cloud

Adobe Commerce only: push a branch and the platform runs the build, deploy and post_deploy hooks from .magento.app.yaml.

Syntaxphp ./vendor/bin/ece-tools run scenario/deploy.xml

Adobe Commerce on cloud infrastructure is Adobe's hosted platform. It is part of Adobe Commerce. Magento Open Source cannot use it, and the files described here exist only in a cloud project. You deploy by pushing a Git branch. The platform then runs three phases, and you control what happens in each from .magento.app.yaml.

The three hooks

The build hook runs before the application is packaged, with no database, Redis or OpenSearch available. This is where composer install, DI compilation and static content deployment happen. The deploy hook runs once the filesystem is mounted and services are up, with the site in maintenance mode; it imports configuration and upgrades the database. The post_deploy hook runs after the container starts accepting connections, and is where the cache is warmed.

Mounts

After the build, the filesystem is read-only except for four paths: app/etc, pub/media, pub/static and var. Whatever your build hook wrote elsewhere is baked into the image and survives. Whatever your deploy hook tries to write elsewhere fails.

Environments

A Pro project has master, integration, staging and production, with staging and production on dedicated infrastructure. A Starter project has master, staging and up to two integration branches, all in shared containers. Variables that tune the phases live in .magento.env.yaml, separately from the hooks.

Example

Example · yaml
# .magento.app.yaml - the deployment hooks of a cloud project
hooks:
    # no database, no Redis, no OpenSearch: nothing that boots the app with a connection
    build: |
        set -e
        composer install
        npm --prefix app/design/frontend/Vendor/shop ci      # custom work goes first
        npm --prefix app/design/frontend/Vendor/shop run build
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml

    # services are up, site is in maintenance mode; this relocates app/etc
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml
        php -f bin/magento indexer:reindex catalogsearch_fulltext   # custom work goes last

    # the container is already taking traffic
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml

When to use it

  • Add a theme asset build step to the build hook without breaking the ece-tools scenarios.
  • Work out why a module that writes files locally fails on a cloud deploy.
  • Tune static content deployment when the build container runs out of disk or time.
  • Decide whether a feature you read about needs Adobe Commerce or works on Open Source.

More examples

Phase variables, kept out of the hooks

Edit this rather than the hooks when you want to change how a phase behaves. SCD_STRATEGY and SCD_THREADS control the static content build, and compact is the one to reach for when the build container runs out of disk. CRON_CONSUMERS_RUNNER writes the cron_consumers_runner block of env.php on every deploy, which is why editing that block by hand on a cloud environment does not stick. _merge: true keeps the platform's generated cache settings and adds yours on top.

Example · yaml
# .magento.env.yaml - read by ece-tools during build and deploy
stage:
  build:
    SCD_STRATEGY: "compact"      # quick (default), standard, or compact
    SCD_THREADS: 3
  deploy:
    CRON_CONSUMERS_RUNNER:
      cron_run: true
      max_messages: 1000
      consumers:
        - async.operations.all
        - product_action_attribute.update
    CACHE_CONFIGURATION:
      _merge: true

The four writable paths

Read this list when a deploy fails with a permission error on a path that works locally. A module that writes a cache file, a log or a generated asset outside these four paths works in development and fails on cloud, because the container filesystem is read-only everywhere else. Writing into var/ is the usual fix. Note also that mounted paths are not part of the build artefact: a file your build hook writes into var/ is gone by the time the deploy phase starts.

Example · yaml
# .magento.app.yaml - everything not listed here is read-only after the build
mounts:
    "var":
        source: local
        source_path: "var"
    "app/etc":
        source: local
        source_path: "etc"
    "pub/media":
        source: local
        source_path: "media"
    "pub/static":
        source: local
        source_path: "pub/static"

Driving an environment from your workstation

Use the CLI rather than the Cloud Console for anything you want to repeat or script. environment:ssh is how you get a shell to run bin/magento on an environment; db:dump is how you get a copy of the data to work against locally. There is no root on these containers and no package installation, so a debugging step that needs a system tool has to be solved another way. Pushing a branch is the deploy, so environment:push and git push do the same thing.

Example · bash
# the magento-cloud CLI, installed locally and authenticated once
magento-cloud environment:list
magento-cloud environment:ssh -e staging
magento-cloud db:dump -e staging
magento-cloud environment:push -e integration

# ID            Title        Status
# master        Master       Active
# staging       Staging      Active
# production    Production   Active
# feature-tier  feature-tier Active

Related

m2 build cim2 deploy upgradem2 deploy consumersm2 stackm2 mode production

Discussion

  • Be the first to comment on this lesson.