Properties for application configuration

The .magento.app.yaml file uses properties to manage environment support for the Commerce application.

Name
Description
Default
Required
access
Customize user roles
No
crons
Update specs and schedule cron jobs
No
dependencies
Enable additional dependencies
php:composer/composer: '2.2.4'
No
disk
Define the persistent disk size
5120
Yes
firewall
(Starter only) Control outbound traffic
No
hooks
Customize shell commands for the build, deploy, and post-deploy phases
No
mounts
Set paths

Paths:

  • "var": "shared:files/var"
  • "app/etc": "shared:files/etc"
  • "pub/media": "shared:files/media"
  • "pub/static": "shared:files/static"
No
name
Define the application name
mymagento
Yes
relationships
Map services

Services:

  • database: "mysql:mysql"
  • redis: "redis:redis"
  • opensearch: "opensearch:opensearch"
No
runtime
Runtime property includes extensions that are required by the Commerce application.

Extensions:

  • xsl
  • newrelic
  • sodium
Yes
type
Set the base container image
php:8.3
Yes
variables
Apply an environment variable for a specific Commerce version
No
web
Handle external requests
Yes
workers
Handle external requests
Yes, if not using the web property

name

The name property provides the application name used in the routes.yaml file to define the HTTP upstream (by default, mymagento:http). For example, if the value of name is app, you must use app:http in the upstream field.

WARNING
Do not change the name of the application after it has been deployed. Doing so results in data loss.

type and build

The type and build properties provide information about the base container image to build and run the project.

The supported type language is PHP. Specify the PHP version as follows:

type: php:<version>

The build property determines what happens by default when building the project. The flavor specifies a default set of build tasks to run. The following example shows the default configuration for type and build from magento-cloud/.magento.app.yaml:

# The toolstack used to build the application.
type: php:8.3
build:
    flavor: none

dependencies:
    php:
        composer/composer: '2.7.2'

Installing and using Composer 2

The build: flavor: property is not used for Composer 2.x; therefore, you must manually install Composer during the build phase. To install and use Composer 2.x in your Starter and Pro projects, you must make three changes to your .magento.app.yaml configuration:

  1. Remove composer as the build: flavor: and add none. This change prevents Cloud from using the default 1.x version of Composer to run build tasks.
  2. Add composer/composer: '^2.0' as a php dependency for installing Composer 2.x.
  3. Add the composer build tasks to a build hook to run the build tasks using Composer 2.x.

Use the following configuration fragments in your own .magento.app.yaml configuration:

# 1. Change flavor to none.
build:
    flavor: none

# 2. Add Composer ^2.0 as a php dependency.
dependencies:
    php:
        composer/composer: '^2.0'

# 3. Add a build hook to run the build tasks using Composer 2.x.
hooks:
    build: |
        set -e
        composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader

See Required packages for more information about Composer.

dependencies

Specify dependencies that your application might need during the build process.

Adobe Commerce supports dependencies on the following languages:

  • PHP
  • Ruby
  • Node.js

Those dependencies are independent of the eventual dependencies of your application, and are available in the PATH, during the build process and in the runtime environment of your application.

You can specify those dependencies as follows:

ruby:
   sass: "~3.4"
nodejs:
   grunt-cli: "~0.3"

runtime

Use to modify the PHP configuration at runtime, such as enabling extensions. The following extensions are required:

runtime:
    extensions:
        - xsl
        - newrelic
        - sodium

See PHP settings for details about enabling extensions.

disk

Defines the persistent disk size of the application in MB.

disk: 5120

The minimal recommended disk size is 256 MB. If you see the error UserError: Error building the project: Disk size may not be smaller than 128MB, increase the size to 256 MB.

NOTE
For Pro Staging and Production environments, you must Submit an Adobe Commerce Support ticket to update the mounts and disk configuration for your application. When you submit the ticket, indicate the required configuration changes and include an updated version of your .magento.app.yaml file.
It is not possible to temporarily increase the disk storage in Staging or Production; this process is not reversible.

relationships

Defines the service mapping in the application.

The relationship name is available to the application in the MAGENTO_CLOUD_RELATIONSHIPS environment variable. The <service-name>:<endpoint-name> relationship maps to the name and type values defined in the .magento/services.yaml file.

relationships:
    <name>: "<service-name>:<endpoint-name>"

The following is an example of the default relationships:

relationships:
    database: "mysql:mysql"
    redis: "redis:redis"
    opensearch: "opensearch:opensearch"
    rabbitmq: "rabbitmq:rabbitmq"

See Services for a full list of currently supported service types and endpoints.

mounts

An object whose keys are paths relative to the root of the application. The mount is a writable area on the disk for files. The following is a default list of mounts configured in the magento.app.yaml file using the volume_id[/subpath] syntax:

 # The mounts that will be performed when the package is deployed.
mounts:
    "var": "shared:files/var"
    "app/etc": "shared:files/etc"
    "pub/media": "shared:files/media"
    "pub/static": "shared:files/static"

The format for adding your mount to this list is as follows:

"/public/sites/default/files": "shared:files/files"
  • shared—Shares a volume between your applications inside an environment.
  • disk—Defines the size available for the shared volume.
NOTE
For Pro Staging and Production environments, you must Submit an Adobe Commerce Support ticket to update the mounts and disk configuration for your application. When you submit the ticket, indicate the required configuration changes and include an updated version of your .magento.app.yaml file.

You can make the mount web accessible by adding it to the web block of locations.

WARNING
Once your site has data, do not change the subpath portion of the mount name. This value is the unique identifier for the files area. If you change this name, you lose all site data stored at the old location.

access

The access property indicates a minimum user role level that is allowed SSH access to the environments. The available user roles are:

  • admin—Can change settings and execute actions in the environment; has contributor and viewer rights.
  • contributor—Can push code to this environment and branch from the environment; has viewer rights.
  • viewer—Can view the environment only.

The default user role is contributor, which restricts the SSH access from users with only viewer rights. You can change the user role to viewer to allow SSH access for users with only viewer rights:

access:
    ssh: viewer
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26