Cloud 3.03

Environment Configuration

Adding configurations to environments using .magento.app.yaml, web section, hooks, and understanding file availability.

Exam Critical: Understanding environment configuration files, especially .magento.app.yaml and where each file is used, is essential for the AD0-E717 exam! Know the web section, hooks, mounts, and environment availability.

Environment Configuration

mindmap root((Environment Config)) Four Files app.yaml services.yaml routes.yaml env.yaml app.yaml Sections access SSH roles crons jobs hooks build deploy mounts writable dirs relationships services web locations Web Section locations config root passthru index rules patterns Environment Availability Starter all files Pro Integration all Pro Staging Production limited

Four Primary Configuration Files

Overview

Cloud environments are configured using four primary files:

File	Purpose	Availability
`.magento.app.yaml`	Primary application configuration	All environments (Starter + Pro)
`.magento/services.yaml`	Configure MySQL, Redis, Elasticsearch, RabbitMQ	Starter: All, Pro: Integration only
`.magento/routes.yaml`	Configure caching and redirects	All environments (Starter + Pro)
`.magento.env.yaml`	Stage-specific environment variables	All environments

.magento.app.yaml Configuration

Primary Application Configuration

This is where the primary application configuration occurs. Key sections:

access: SSH Access Control

Declares the minimum user role that has SSH access:

access:
    ssh: contributor

Available Roles

admin: Full access
contributor: Can push code and branch
viewer: View-only access

crons: Cron Job Configuration

Configure cron jobs to run in the environment:

crons:
    cronrun:
        spec: "* * * * *"
        cmd: "php bin/magento cron:run"

hooks: Build, Deploy, and Post-Deploy

Three sections for different deployment stages:

hooks:
    build: |
        set -e
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml
    post_deploy: |
        php ./vendor/bin/ece-tools run scenario/post-deploy.xml

Hook Stages

build: Compile code, generate static content (no DB access)
deploy: Deploy to environment (read-only filesystem)
post_deploy: After deployment, application available (cache warming)

mounts: Writable Directories

Configure writable directories in otherwise read-only filesystem:

mounts:
    "var": "shared:files/var"
    "app/etc": "shared:files/etc"
    "pub/media": "shared:files/media"
    "pub/static": "shared:files/static"

Default Writable Directories

var/ - Logs, cache, sessions
app/etc/ - env.php and config.php
pub/media/ - Uploaded media files
pub/static/ - Generated static content

Making Directories Browsable

To make a writable directory browsable on frontend:

Add it to mounts section
Add it to web section locations

name: Application Name

Must match the name specified in .magento/routes.yaml:

name: mymagento

Important

This name must match the upstream value in routes.yaml (e.g., upstream: "mymagento:http")

relationships: Connect to Services

Makes services available to the Magento application:

relationships:
    database: "mysql:mysql"
    redis: "redis:redis"
    elasticsearch: "elasticsearch:elasticsearch"
    rabbitmq: "rabbitmq:rabbitmq"

dependencies: Build and Deploy Packages

Specify packages to include in build and deploy environments:

dependencies:
    ruby:
        sass: "3.4.22"
    nodejs:
        gulp-cli: "^2.0.0"
        yarn: "^1.15.2"

Supported Languages

ruby: Ruby packages
nodejs: Node.js packages

runtime/extensions: PHP Extensions

Add PHP extensions to the environment:

runtime:
    extensions:
        - redis
        - xsl
        - imagick
        - blackfire
        - newrelic

Required Extensions

redis: Required for Redis functionality
xsl: Required for XML transformations
imagick: Required for image processing

Recommended for Cloud

blackfire: Performance profiling
newrelic: Application monitoring

variables: Environment Variables

Environment variables can be set in four places:

Location	Scope	Use Case
`.magento.app.yaml`	Global, all environments (code-based)	Default configuration in code
`.magento.env.yaml`	Stage-specific (global, build, deploy, post-deploy)	Stage-specific settings, notifications, logs
Web admin (per environment)	Specific environment	Environment-specific overrides
Web admin (project level)	Entire project	Project-wide settings

web Section (Critical)

Powerful Web Configuration

The web section represents an incredibly powerful portion of Cloud configuration.

Important Note

The document_root, passthru at the top level are deprecated. Focus on web/locations configuration.

web/locations Configuration

Each exposed location is a key inside locations:

web:
    locations:
        "/":
            root: "pub"
            passthru: "/index.php"
            index:
                - index.php
            scripts: true
            allow: false
            rules:
                \\.css$:
                    allow: true
                \\.js$:
                    allow: true
                \\.png$:
                    allow: true
        "/media":
            root: "pub/media"
            passthru: "/get.php"
            scripts: false
            allow: true
        "/static":
            root: "pub/static"
            passthru: "/front-static.php"
            scripts: false
            allow: true
            rules:
                ^/static/version\\d+/(?.*)$:
                    passthru: "/static/$resource"

Location Configuration Options

root

The root directory that is served:

For /: Usually pub
For custom PWA: Might be different path
For /media: pub/media
For /static: pub/static

passthru

Root file for the website if requested resource not found:

For /: /index.php (Magento application)
For /media: /get.php (media handler)
For /static: /front-static.php (static handler)

How Passthru Works

If user requests catalog/product/view/id/1981, that path doesn't exist as a file, so the passthru file picks it up (Magento handles routing).

index

Which index files are accepted:

For Magento: index.php
For static directories: Might not be set

scripts

true: For applications (allows PHP execution)
false: For static content (no script execution)

allow

Whether to allow static files:

Default for /: false (then overridden by rules)
Default for /media and /static: true

rules: Pattern Matching

Rules define behavior for specific patterns:

allow: Static File Access

Whether to allow regex pattern when it matches a static file:

rules:
    \\.css$:
        allow: true
    \\.js$:
        allow: true
    \\.png$:
        allow: true
    \\.gif$:
        allow: true
    \\.jpg$:
        allow: true

passthru: URL Rewriting

Map request to another path (static content versioning example):

rules:
    ^/static/version\\d+/(?.*)$:
        passthru: "/static/$resource"

What This Does

Handles static content signing signature by rewriting:

/static/version1234567/frontend/Theme/locale/style.css

→ /static/frontend/Theme/locale/style.css

Custom php.ini Configuration

You can create a custom php.ini file to control PHP configuration:

Location

Root project directory: php.ini

Behavior

Configuration is appended/merged with existing Magento Cloud configuration.

Example

memory_limit = 2G
max_execution_time = 1800
upload_max_filesize = 64M
post_max_size = 64M

Environment File Availability

Critical Differences: Starter vs Pro

File	Starter	Pro Integration	Pro Staging	Pro Production
`.magento.app.yaml`	✓ Used	✓ Used	✓ Used	✓ Used
`.magento/services.yaml`	✓ Used	✓ Used	✗ Not Available	✗ Not Available
`.magento/routes.yaml`	✓ Used	✓ Used	✓ Used	✓ Used
`.magento.env.yaml`	✓ Used	✓ Used	✓ Used	✓ Used

Critical Warning

.magento/services.yaml is NOT available in Pro Staging and Production!

If you enable Elasticsearch in services.yaml, configure relationships in app.yaml, and deploy to Pro Production, you may encounter problems. Services must be configured via support ticket for Pro Staging/Production.

Viewing Environment Relationships

Check Configured Services

To view all configured relationships in an environment:

php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"])));'

What This Shows

All configured services
Connection details (host, port, username, password)
Service endpoints
Relationship names

Practical Experience

Hands-On Tasks

Deploy a new service: Add to services.yaml, configure relationship, check with MAGENTO_CLOUD_RELATIONSHIPS
Configure new mount point: Add to mounts section, make browsable via web section
Test custom php.ini: Create php.ini, deploy, verify settings
Modify web locations: Add custom location or rules

Best Practices

Do's

Use .magento.env.yaml for stage-specific configs
Focus on web/locations (not deprecated top-level)
Test in Integration before Staging/Production
Match name in app.yaml with routes.yaml
Include required PHP extensions
Document custom configurations
Use proper SSH access roles

Don'ts

Don't use deprecated document_root/passthru
Don't forget services.yaml unavailable in Pro Staging/Prod
Don't configure services without support ticket (Pro)
Don't make all directories writable
Don't forget to add extensions to web locations
Don't mismatch app.yaml name with routes.yaml

Exam Tips

Key Points to Remember

Four files: app.yaml, services.yaml, routes.yaml, env.yaml
app.yaml sections: access, crons, hooks, mounts, name, relationships, dependencies, runtime/extensions, variables, web
SSH access roles: admin, contributor, viewer
Hook stages: build (no DB), deploy (read-only), post_deploy (app available)
Default mounts: var/, app/etc/, pub/media/, pub/static/
Required PHP extensions: redis, xsl, imagick
Recommended extensions: blackfire, newrelic
Variable locations: app.yaml (global), env.yaml (stage-specific), web admin (per environment/project)
Web section: Focus on locations (document_root deprecated)
Location keys: root, passthru, index, scripts, allow, rules
Default locations: /, /media, /static
Passthru files: /index.php, /get.php, /front-static.php
Custom php.ini: Root directory, merged with Cloud config
File availability: services.yaml NOT in Pro Staging/Production
All environments use: app.yaml, routes.yaml, env.yaml

Previous: Cloud 3.02 Services Practice Cloud 3.03

Environment Configuration