Application

Edit on GitHub
Log an Issue

The .magento.app.yaml file controls the way your application builds and deploys. Although Magento Commerce Cloud supports multiple applications per project, typically, a project has a single application with the .magento.app.yaml file at the root of the repository.

The .magento.app.yaml has many default values, see a sample .magento.app.yaml file. Always review the .magento.app.yaml for your installed version. This file can differ across Magento Commerce Cloud versions.

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:

Attribute Description
root The path relative to the root of the application that is exposed on the web. Typical values include /public and /web.
passthru The URL used in the event that a static file or PHP file cannot be found. This URL is typically the front controller for your applications, often /index.php or /app.php.
index Static files, such as index.html, to serve your application. This key expects a collection. You must include the static file(s) in the whitelist as an index file, like - \.html$.
blacklist A list of files that should never be executed. Has no effect on static files.
whitelist A list of static files (as regular expressions) that can be served. Dynamic files (for example, PHP files) are treated as static files and have their source code served, but they are not executed.
expires The number of seconds to cache whitelisted content in the browser. This attribute enables the cache-control and expires headers for static content. If this value is not set, the expires directive and resulting headers are not included when serving static content files.

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.

Variables

The following environment variables are included in .magento.app.yaml. These are required for Magento Commerce Cloud 2.2.x.

1
2
3
4
5

variables:
    env:
        CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
        CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL: 'Magento_Enterprise_Cloud_BT'
        CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'

Configure PHP options

You can choose which version of PHP to run in your .magento.app.yaml file:

1
2

name: mymagento
type: php:<version>

PHP extensions

You can enable additional PHP extensions in the runtime:extension section. Also, the extensions specified become available in the Docker PHP containers.

.magento.app.yaml

1
2
3
4
5
6
7
8
9
10

runtime:
    extensions:
        - sockets
        - sodium
        - ssh2
    disabled_extensions:
        - bcmath
        - bz2
        - calendar
        - exif

Use SSH to log in to an environment and list the PHP extensions.

1

php -m

For details about a specific PHP extension, see the PHP Extension List.

Magento Commerce Cloud supports the following extensions:

  • Default extensions:
    • bcmath
    • bz2
    • calendar
    • exif
    • gd
    • gettext
    • intl
    • mysqli
    • pcntl
    • pdo_mysql
    • soap
    • sockets
    • sysvmsg
    • sysvsem
    • sysvshm
    • opcache
    • zip
  • Extensions that are installed and cannot be uninstalled:
    • ctype
    • curl
    • date
    • dom
    • fileinfo
    • filter
    • ftp
    • hash
    • iconv
    • json
    • mbstring
    • mysqlnd
    • openssl
    • pcre
    • pdo
    • pdo_sqlite
    • phar
    • posix
    • readline
    • session
    • sqlite3
    • tokenizer
    • xml
    • xmlreader
    • xmlwriter
  • Extensions that can be installed and uninstalled as needed:
    • bcmath
    • bz2
    • calendar
    • exif
    • gd
    • geoip
    • gettext
    • gmp
    • igbinary
    • imagick
    • imap
    • intl
    • ioncube
    • ldap
    • mailparse
    • mcrypt
    • msgpack
    • mysqli
    • oauth
    • opcache
    • pdo_mysql
    • propro
    • pspell
    • raphf
    • recode
    • redis
    • shmop
    • soap
    • sockets
    • sodium
    • ssh2
    • sysvmsg
    • sysvsem
    • sysvshm
    • tidy
    • xdebug
    • xmlrpc
    • xsl
    • yaml
    • zip
    • pcntl

PHP compiled with debug is not supported and the Probe may conflict with XDebug or XHProf. Disable those extensions when enabling the Probe. The Probe conflicts with some PHP extensions like Pinba or IonCube.

Customize php.ini settings

You can also create and push a php.ini file that is appended to the configuration maintained by Magento Commerce.

In your repository, the php.ini file should be added to the root of the application (the repository root).

Configuring PHP settings improperly can cause issues. We recommend only advanced administrators set these options.

For example, if you need to increase the PHP memory limit:

1

memory_limit = 756M

For a list of recommended PHP configuration settings, see Required PHP settings.

After pushing your file, you can check that the custom PHP configuration has been added to your environment by creating an SSH tunnel to your environment and entering:

1

cat /etc/php5/fpm/php.ini

If you use Magento Cloud Docker for local development, see [Docker service containers]//cloud/docker/docker-containers-service.html#fpm-container) for information about using a custom php.ini file in a Docker environment.

Workers

You can define zero or multiple work instances for each application. A worker instance runs as a container, independent from the web instance and without a running Nginx instance. Additionally, you do not need to set up a web server on the worker instance (using Node.js or Go) because the router cannot direct public requests to the worker.

A worker instance has the exact same code and compilation output as a web instance. The container image is built once and deployed multiple times if needed using the same build hook and dependencies. You can customize the container and allocated resources.

Use worker instances for background tasks including:

  • Tasks like queue workers or updating indexes.
  • Tasks to run periodic reporting that are too long for a cron job.
  • Tasks should happen “now”, but not block a web request.
  • Tasks are large enough that they risk blocking a deploy, even if they are subdivided.
  • The task in question is a continually running process rather than a stream of discrete units of work.

A basic, common worker configuration could look like this:

1
2
3
4
5
6

workers:
    queue:
        size: S
        commands:
            start: |
                php worker.php

This example defines a single worker named queue, with a “small” container, and runs the command php worker.php on startup. If worker.php exits, it is automatically restarted.

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 does not require additional configuration.

© 2020 Magento. All rights reserved.