Properties

Use the following properties to build your application configuration file. The name, type, disk, and one web or worker block is required.

For Pro Staging and Production environments, you must submit a 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.

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.

Do not change the name of the application after it has been deployed. Doing so will result 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:

1
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 supported flavor is composer.

1
2
build:
    flavor: composer

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. Also has contributor and viewer rights.
• contributor—Can push code to this environment and branch from the environment. Also 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:

1
2
access:
    ssh: viewer

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.

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

The following is an example of the default relationships:

1
2
3
4
relationships:
    database: "mysql:mysql"
    redis: "redis:redis"
    elasticsearch: "elasticsearch:elasticsearch"

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

web

The web property defines how your application is exposed to the web (in HTTP). It determines how the web application serves content— from the front-controller script to a non-static request to an index.php file on the root. We support any directory structure so the static file can be in a sub directory, and the index.php file can be further down.

You can specify the following attributes for the web property:

Contrary to standard .htaccess approaches that accept a blacklist and allow access to everything not on a specific list, we accept a whitelist, which means that any request that does not match triggers a 404 error and passes through to the URL specified by the passthru attribute.

Our default configuration allows the following:

• From the root (/) path, only web and media can be accessed
• From the ~/pub/static and ~/pub/media paths, any file can be accessed

The following example shows the default configuration for a set of web-accessible locations associated with an entry in the mounts property:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 # The configuration of app when it is exposed to the web.
web:
    locations:
        "/":
            # The public directory of the app, relative to its root.
            root: "pub"
            # The front-controller script to send non-static requests to.
            passthru: "/index.php"
            index:
                - index.php
            expires: -1
            scripts: true
            allow: false
            rules:
                \.(css|js|map|hbs|gif|jpe?g|png|tiff|wbmp|ico|jng|bmp|svgz|midi?|mp?ga|mp2|mp3|m4a|ra|weba|3gpp?|mp4|mpe?g|mpe|ogv|mov|webm|flv|mng|asx|asf|wmv|avi|ogx|swf|jar|ttf|eot|woff|otf|html?)$:
                    allow: true
                ^/sitemap(.*)\.xml$:
                    passthru: "/media/sitemap$1.xml"
        "/media":
            root: "pub/media"
            allow: true
            scripts: false
            expires: 1y
            passthru: "/get.php"
        "/static":
            root: "pub/static"
            allow: true
            scripts: false
            expires: 1y
            passthru: "/front-static.php"
            rules:
                ^/static/version\d+/(?<resource>.*)$:
                    passthru: "/static/$resource"

This example shows the default web configuration for a Cloud project configured to support a single domain. For a project that requires support for multiple websites or stores, the web configuration must be set up to support shared domains. See Configure locations for shared domains.

disk

Defines the persistent disk size of the application in MB.

1
disk: 2048

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

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:

1
2
3
4
5
6
 # 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:

1
"/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.

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

Once your Magento 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 will lose all site data stored at the old location.

dependencies

Enables you to specify dependencies that your application might need during the build process.

Magento Commerce supports dependencies on the following languages:

• PHP
• Ruby
• NodeJS

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:

1
2
3
4
ruby:
   sass: "~3.4"
nodejs:
   grunt-cli: "~0.3"

hooks

Use the hooks section to run shell commands during the build, deploy, and post-deploy phases:

• build—Execute commands before packaging your application. Services, such as the database or Redis, are not available at this time since the application has not been deployed yet. You must add custom commands before the default php ./vendor/bin/ece-tools command so that custom-generated content continues to the deployment phase.

• deploy—Execute commands after packaging and deploying your application. You can access other services at this point. Since the default php ./vendor/bin/ece-tools command copies the app/etc directory to the correct location, you must add custom commands after the deploy command to prevent custom commands from failing.

• post_deploy—Execute commands after deploying your application and after the container begins accepting connections. The post_deploy hook clears the cache and preloads (warms) the cache. You can customize the list of pages using the WARM_UP_PAGES variable in the Post-deploy stage. Although not required, this works in tandem with the SCD_ON_DEMAND environment variable.

Add CLI commands under the build, deploy, or post_deploy sections before the ece-tools command:

1
2
3
4
5
6
7
8
9
10
11
12
hooks:
    # We run build hooks before your application has been packaged.
    build: |
        set -e
        php ./vendor/bin/ece-tools build:generate
        php ./vendor/bin/ece-tools build:transfer
    # We run deploy hook after your application has been deployed and started.
    deploy: |
        php ./vendor/bin/ece-tools deploy
    # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10.
    post_deploy: |
        php ./vendor/bin/ece-tools post-deploy

Also, you can customize the build phase further by using the generate and transfer commands to perform additional actions when specifically building code or moving files.

1
2
3
4
5
6
7
hooks:
    # We run build hooks before your application has been packaged.
    build: |
        set -e
        php ./vendor/bin/ece-tools build:generate
        # php /path/to/your/script
        php ./vendor/bin/ece-tools build:transfer

• set -e—causes hooks to fail on the first failed command, instead of the final failed command.
• build:generate—applies patches, validates configuration, generates DI, and generates static content if SCD is enabled for build phase.
• build:transfer—transfers generated code and static content to the final destination.

The commands run from the application (/app) directory. You can use the cd command to change the directory. The hooks fail if the final command in them fails. To cause them to fail on the first failed command, add set -e to the beginning of the hook.

To compile Sass files using grunt:

1
2
3
4
5
6
7
8
9
10
11
12
13
dependencies:
    ruby:
        sass: "3.4.7"
    nodejs:
        grunt-cli: "~0.1.13"

hooks:
    build: |
        cd public/profiles/project_name/themes/custom/theme_name
        npm install
        grunt
        cd
        php ./vendor/bin/ece-tools build

You must compile Sass files using grunt before static content deployment, which happens during the build. Place the grunt command before the build command.

With ece-tools 2002.1.0 and later, you can use the scenario-based deployment feature to customize the build, deploy, and post-deploy processes for your Magento Commerce Cloud project. See Scenario-based deployment.

crons

Describes processes that are triggered on a schedule. We recommend you run cron as the Magento file system owner. Do not run cron as root or as the web server user.

crons support the following:

• spec—The cron specification. For Starter environments and Pro Integration environments, the minimum interval is once per five minutes and once per one minute in Pro Staging and Production environments. You need to complete additional configurations for crons in those environments.
• cmd—The command to execute.

A cron job is well suited for the following tasks:

• They need to happen on a fixed schedule, not continually.
• The task itself is not especially long, as a running cron job will block a new deployment.
• Or it is long, but can be easily divided into many small queued tasks.
• A delay between when a task is registered and when it actually happens is acceptable.

By default, every Cloud project has the following default crons configuration to run the default Magento cron jobs:

1
2
3
4
crons:
    cronrun:
        spec: "* * * * *"
        cmd: "php bin/magento cron:run"

For Magento Commerce Cloud 2.1.x, you can use only workers and cron jobs. For Magento Commerce Cloud 2.2.x, cron jobs launch consumers to process batches of messages, and do not require additional configuration.

If your project requires custom cron jobs, you can add them to the default cron configuration. See Set up cron jobs.