Deployment Process

Three Main Phases

Build Process Overview

The build process is configured in .magento.app.yaml with additional configurations in .magento.env.yaml.

Primary build command in .magento.app.yaml:

hooks:
    build: |
        php ./vendor/bin/ece-tools build

1. composer install (automatic, before hooks/build)
2. Run hooks/build commands from .magento.app.yaml
3. php ./vendor/bin/ece-tools build must be run
4. Run custom commands (optional)

The ece-tools build command is an alias that runs two commands:

Build:Generate Sub-Commands

This command executes a series of sub-commands. Understanding the order is important, not memorizing method names.

1. PreBuild

• Outputs "Verbosity level is..."
• Cleans generated/code directory
• Cleans generated/metadata directory

2. SetProductionMode

• Uses DeployConfigWriter to write to env.php
• Sets application to production mode

3. ValidateConfiguration

Executes multiple validators:

4. ModuleRefresh

• Enables all modules

5. ApplyPatches

Applies patches and configures filesystem:

• copyStaticFile: Copies pub/static.php to pub/front-static.php
• applyComposerPatches: Applies composer module patches from patches.json
• applyHotFixes: Applies all .patch files from m2-hotfixes directory

6. MarshallFiles

• Deletes var/cache directory
• Copies di.xml files (if Magento < 2.2)

7. CopySampleData

• If vendor/magento/sample-data-media exists, copies media to pub/media

8. CompileDi

• Runs bin/magento setup:di:compile
• Generates dependency injection configuration

9. ComposerDumpAutoload

• Regenerates Composer's autoload_classmap.php
• Necessary because additional files may have been added since composer install

10. DeployStaticContent

Optionally deploys static content during build phase (IDEAL for production!):

When conditions are met, runs: bin/magento setup:static-content:deploy

Prepare Slug for Deployment

After generation completes, the next step prepares the "slug" (artifact/archive) for deployment.

1. CompressStaticContent

Uses these variables:

• SCD_COMPRESSION_LEVEL
• SCD_COMPRESSION_TIMEOUT
• VERBOSE_COMMANDS

Sample compression command:

timeout -k 30 30 bash -c \
find pub/static -type d -name DELETING_* -prune -o -type f -size +300c \
'(' -name '*.js' -or -name '*.css' -or -name '*.svg' \
    -or -name '*.html' -or -name '*.htm' ')' -print0 \
| xargs -0 -n100 -P16 gzip -q --keep -4

2. ClearInitDirectory

• Clears contents of init/ directory
• Removes app/etc/env.php

3. BackupData

Copies static content and writable directories to init directory:

Deploy Process Overview

The deploy process has two parts:

1. Mount the filesystem, configure connections and services
2. Execute deploy commands in .magento.app.yaml

hooks:
    deploy: |
        php ./vendor/bin/ece-tools deploy

PreDeploy Sub-Commands

1. ConfigUpdate\Cache

Updates cache configuration in app/etc/env.php:

• If CACHE_CONFIGURATION is valid and matches app/etc/env.php, no changes
• If using Redis slave (REDIS_USE_SLAVE_CONNECTION), those details won't update in env.php
• If no Redis relationship exists, nothing happens
• Otherwise, app/etc/env.php is updated with cache (default) and page_cache info

2. CleanStaticContent

• If static content was built OR CLEAN_STATIC_FILES variable is missing, nothing happens
• Otherwise, cleans content from pub/static directory

3. CleanViewPreprocessed

• If SKIP_HTML_MINIFICATION is absent (HTML is minified), does nothing
• Otherwise, var/view_preprocessed directory is cleaned

4. CleanRedisCache

• Clears all Redis caches (default and page_cache)

5. CleanFileCache

• Cleans var/cache directory if it exists

6. RestoreWritableDirectories

Copies or symlinks files from init/ directory:

• init/app/etc/* → copied to root-level locations
• init/pub/media → copied to root-level

If static content was built in build phase:

• If HTML is minified, copy init/var/view_preprocessed
• Copy all files in init/pub/static

7. SetProductionMode

• Enables production mode in app/etc/env.php

8. DisableCron

• Turns off cron by updating app/etc/env.php

9. ValidateConfiguration

Runs multiple configuration validators:

Two Paths: Install vs Update

If Magento is NOT Installed (Install Path)

1. UnlockCronJobs

• If Magento ≥ 2.2.2, automatically sets running cron jobs to error status
• Allows setup upgrade to proceed without cron locks

2. SetCryptKey

• If no encryption key in app/etc/env.php AND CRYPT_KEY env variable is set, saves to env.php
• Should only happen on initial install

3. InstallUpdate → Setup

Runs setup:install with these notes:

• Must specify ADMIN_EMAIL environment variable for automated install
• Sessions saved to database by default
• Connection info loaded from configuration merged with env variables

4. ConfigUpdate

After install, runs configuration updates (see Update path below)

5. ConfigImport

• Runs bin/magento app:config:import
• Imports config from app/etc/env.php and app/etc/config.php into database

6. ResetPassword

• Notifies admin of admin URL (doesn't actually reset password!)
• Only runs at install time

If Magento IS Installed (Update Path)

1. ConfigUpdate

Runs multiple configuration updaters:

2. SetAdminUrl

• If admin URL defined as environment variable, configures backend/frontName

3. Setup

• Runs bin/magento setup:upgrade --keep-generated

Static Content Deployment (Default Location)

Building static content in deploy phase is the DEFAULT (but not ideal for production).

When SCD Runs on Deploy

Generate Static Content

• Checks if pub/static directory is writable
• Generates bin/magento setup:static-content:deploy commands

Variables Used

• SCD_THREADS: Number of threads
• SCD_STRATEGY: Deployment strategy
• SCD_MAX_EXEC_TIME: Applied to --max-execution-time

CompressStaticContent

• If SCD_ON_DEMAND, SKIP_SCD, or SCD in build phase: no compression
• Otherwise, compresses pub/static directory

DisableGoogleAnalytics

• If staging/integration branches and ENABLE_GOOGLE_ANALYTICS disabled (default), GA is disabled

Final Deploy Steps

Only runs if there is NO post_deploy hook in .magento.app.yaml:

EnableCron

• Removes cron/enabled flag from app/etc/env.php

Backup

• Backs up app/etc/env.php and app/etc/config.php
• Appends .bak extension

CleanCache

• Runs bin/magento cache:flush

Post-Deploy Hook Configuration

# .magento.app.yaml
hooks:
    # ...
    post_deploy: |
        php ./vendor/bin/ece-tools post-deploy

1. DebugLogging Validation

• If this is master branch and debug logging enabled, logs message encouraging you to disable it

2. EnableCron

• Enables cron in app/etc/env.php

3. Backup

• Copies app/etc/env.php and app/etc/config.php
• Appends .bak extension to backups

4. CleanCache

• Runs bin/magento cache:flush

5. WarmUp

Asynchronously crawls pages on the website:

• URLs come from stage/post-deploy/WARM_UP_PAGES in .magento.env.yaml
• Multiple URL pattern types can be used
• Pre-loads cache for better user experience

Why Downtime Occurs

Downtime is a result of the deploy process taking longer than it should.

How to Reduce Downtime

Complete Deployment Process

What Each Phase Does

Validation Phase

• Validates .magento.app.yaml, .magento/services.yaml, .magento/routes.yaml
• Ensures configuration files are syntactically correct

Build Phase

• Prepares code for deployment
• Compiles dependency injection
• Optionally generates static content (IDEAL!)
• No downtime impact

Prepare Slug Phase

• Creates deployment artifact
• Prepares read-only filesystem
• Backs up writable directories to init/

Deploy Slugs & Cluster Phase

• Reconfigures network routing
• 60-second traffic freeze (unavoidable)
• Prepares environment for new code

Deployment Hooks Phase

• deploy: Run migrations, update config, optionally SCD (CAUSES DOWNTIME!)
• post_deploy: Enable cron, warm cache, backup configs (NO DOWNTIME)

Three Methods to Extend ece-tools

Method 1: composer.json psr-4

Use psr-4 section in composer.json to override single classes:

{
    "autoload": {
        "psr-4": {
            "Magento\\MagentoCloud\\": "cloud-patches/src/"
        }
    }
}

Method 2: Git Patches in m2-hotfixes

Create git patches and place in m2-hotfixes/ directory:

• Patches automatically applied during build phase
• Works for any composer package

Method 3: Custom Commands in Hooks

Add custom commands to hooks in .magento.app.yaml:

hooks:
    build: |
        php ./vendor/bin/ece-tools build:generate
        # Your custom build commands here
        php ./custom/build-script.php
        php ./vendor/bin/ece-tools build:transfer
    deploy: |
        php ./vendor/bin/ece-tools deploy
        # Your custom deploy commands here
    post_deploy: |
        php ./vendor/bin/ece-tools post-deploy
        # Your custom post-deploy commands here

Log Locations

Accessing Logs via CLI

# View deploy log
magento-cloud log deploy

# View all logs
magento-cloud log

# SSH and view logs directly
magento-cloud ssh
cat /var/log/deploy.log
cat /app/var/log/cloud.log

Accessing Logs via UI

• Navigate to your environment in Cloud Admin
• Click on deployment activity
• View build, deploy, and post-deploy logs in separate tabs