.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.
.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.
For Pro projects created before October 23, 2017, the changes you make using this YAML file affects your Integration environment only. To make these changes in a Staging or Production environment, you must Add Staging and Production to Pro projects UI.
Use the following properties to build your application configuration file. The
disk, and one
worker block is required.
Magento Commerce supports multiple applications in a project, so you need a unique name that identifies the application in the project. You must use lower case alphanumeric characters, such as
9 for the name.
The name is used in the
routes.yaml file to define the HTTP upstream (by default,
php:http). For example, if the value of
app, you must use
app:http in the upstream field. You can also use this name in multi-application relationships.
Do not change the name of an application after it has been deployed.
build properties provide information about the base container image to build and run the project.
type language is PHP
. Specify the PHP version as follows:
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
build: flavor: composer
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:
access: ssh: viewer
Defines the service mapping in your application.
The left-hand side is the name of the relationship as it will be exposed to the application in the
MAGENTO_CLOUD_RELATIONSHIPS environment 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 value of
type declared in that same file.
Example of valid options are:
database: "mysql:mysql" database2: "mysql2:mysql" cache: "arediscache:redis" search: "searchengine:solr"
See Services for a full list of currently supported service types and endpoints.
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
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 is not 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
The following displays the default set of web accessible locations associated with an entry in
# 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 /robots\.txt$: allow: true "/media": root: "pub/media" allow: true scripts: false passthru: "/index.php" "/static": root: "pub/static" allow: true scripts: false passthru: "/front-static.php" rules: ^/static/version\d+/(?<resource>.*)$: passthru: "/static/$resource"
Defines 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.
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
# 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:
shared—Shares a volume between your applications inside an environment.
disk—Defines the size available for the shared volume.
The subpath portion of the mount is the unique identifier of the files area. If changed, files at the old location will be permanently lost. Do not change this value once your site has data unless you really want to lose all existing data.
You can make the mount web accessible by adding it to the
web block of locations.
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 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-toolscommand 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-toolscommand copies the
app/etcdirectory 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_deployhook clears the cache and preloads (warms) the cache. You can customize the list of pages using the
WARM_UP_PAGESvariable in the Post-deploy stage. It is available only for Pro projects that contain Staging and Production environments in the Project Web UI and for Starter projects. Although not required, this works in tandem with the
Add CLI commands under the
post_deploy sections before the
hooks: # We run build hooks before your application has been packaged. build: | php ./vendor/bin/ece-tools build # 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
transfer commands to perform additional actions when specifically building code or moving files.
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:
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
You must compile Sass files using
grunt before static content deployment, which happens during the build. Place the
grunt command before the
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.
A sample Magento cron job follows:
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.
For more information, see Set up cron jobs.
The following environment variables are included in
.magento.app.yaml. These are required for Magento Commerce Cloud 2.2.X.
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
name: mymagento type: php:7.1
Magento Commerce Cloud supports PHP 7.1 and later. For Pro projects created before October 23, 2017, you must open a support ticket to use PHP 7.1 on your Pro Staging and Production environments.
You can define additional PHP extensions to enable or disable:
runtime: extensions: - xdebug - redis - ssh2 disabled_extensions: - sqlite3
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
Optional PHP extensions available to install:
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.
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:
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
build hook and
dependencies. You can customize the container and
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:
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.