Magento Commerce supports multiple applications per project but typically, a project is composed of a single application, in which case you can simply put a
.magento.app.yaml at the root of your repository.
This file controls the application and the way it is built and deployed on Magento Commerce.
Changes you make using
.yaml files affect your integration environment only. For technical reasons, neither staging nor production environments use
.yaml files. To make these changes in a staging or production environment, you must create a Support ticket.
The following sections discuss properties in
.magento.app.yaml has many default values; see the sample
name identifies the application in the project. Magento Commerce
supports multiple applications in a project, so each application
must have a unique name in a project.
name can consist only of lower case alphanumeric characters; that is,
is used in the
routes.yaml to define the HTTP upstream
For example, if the value of
app, you must use
app:php in the upstream field. You can also use this name in multi-application relationships.
If you change the name you should think about updating your other configuration files (
routes.yaml or the different
.magento.app.yaml, you will have in a multi-application project. Changing the name has no effect on your different services (such as databases).
build properties are used to build and run the project. The only supported
type currently is PHP.
type: php:5.5 type: php:5.6 type: php:7.0
build determines what happens by default when building the project. The only value currently supported is
type: php:5.6 build: flavor: composer
access defines the user roles who can log in using SSH to the
environments to which they have access.
Possible values are:
ssh: admin ssh: contributor ssh: viewer
relationships defines how services are mapped in your
The left-hand side is the name of the relationship as it will be exposed
to the application in the
variable. The right-hand side is in the form
<service name>:<endpoint name>, where
<service name> comes from
<endpoint name> should be the same as the
type declared in that same file.
Example of valid options are:
database: "mysql:mysql" database2: "mysql2:mysql" cache: "arediscache:redis" search: "searchengine:solr"
services.yaml documentation for a full list of currently supported service types and endpoints.
web defines how your application is exposed to the web (in HTTP). Here we tell the web application how to serve 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.
web supports the following:
document_root: The path relative to the root of the application that is exposed on the web. Typical values include
passthru: The URL used in the event a static file or PHP file could not be found. This would typically be your applications front controller, often
index_files: To use a static file (for example,
index.html) to serve your application. This key expects a collection.
For this to work, the static file(s) should be included in your whitelist. For example, to use a file named
index.htmlas an index file, your whitelist should include an element that matches the filename, like
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 whitelisted (that is, static) content should be cached by the browser. This enables the cache-control and Expires headers for static content. The
expiresdirective and resulting headers are left out entirely if this isn’t set.
Contrary to standard
.htaccess approaches, which accept a
blacklist and allow everything to be accessed except a specific
list, we accept a whitelist, which means that anything not matched
will trigger a 404 error and will be passed through to your
Our default configuration allows the following:
- From the root (
/) path, only web, media, and
robots.txtfiles can be accessed
- From the
/pub/mediapaths, any file can be accessed
disk defines the size of the persistent disk size of the
application in MB.
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 is an object whose keys are paths relative to the root of
the application. It’s in the form
The format is:
shared means that the volume is shared between your applications inside an environment. The
disk key defines the size available for that
dependencies enables you to specify dependencies that your
application might need during the build process.
Magento Commerce supports dependencies on the following languages:
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"
hooks (also referred to as
deployment hooks) enable you to define shell
commands to run during the deployment process.
They can be executed at various points in the lifecycle of the application.
Possible hooks are:
build: We run build hooks before your application has been packaged. No other services (such as the database, or redis) are accessible at this time since the application has not been deployed yet.
deploy: We run deploy hooks after your application has been deployed and started. You can access other services at this point.
To add additional hooks (such as CLI commands that are offered by a custom extension), add them under the
deploy sections as follows:
The home directory, where your application is mounted, is
/app, and that is the directory from which hooks will be
run unless you
cd somewhere else.
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.
[Example] Compile SASS files using grunt
For example, to compile SASS files using grunt:
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. We also recommend against running cron as the web server user.
More information about crons:
crons supports the following:
spec: The cron specification. The minimum interval is once per 5 minutes.
cmd: The command to execute.
A sample Magento cron job follows:
crons: cronrun: spec: "*/5 * * * *" cmd: "php bin/magento cron:run"
Configure PHP options
You can choose which version of PHP you want to run in your
We support PHP versions 5.5, 5.6, and 7.0. The default is 7.0.
See one of the following sections for more information:
You can define additional PHP extensions you want to enable or disable. Example:
To view the current list of PHP extensions, SSH into your environment and enter the following command:
Magento requires the following PHP extensions that are enabled by default:
PHP 7 only:
You must install the following extensions:
In addition, we strongly recommend you enable
Other PHP extensions you can optionally install:
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:
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: