Deployment process

Deploying Magento means simply pushing the source code to your Git repository. The Git repository is part of your projects cluster so it is totally isolated from other clients.

The built-in Git repository is at the same time “just a normal Git repository” and a very smart piece of software. When you push to it, it will parse the configuration files you committed to your repository so it knows what it needs to deploy.

If you are pushing directly to the Magento Enterprise Cloud Edition Git repository, you will see in your terminal what is happening in real-time. The same information is going to get streamed in real-time to the Web Interface.

GitHub

If you are using external GitHub repositories, the log of the operations does not display in the GitHub session. You can still follow what’s happening in their interface and in the Magento Enterprise Cloud Edition’s Web Interface.

Project configuration

What makes it all work is a set of YAML configuration files located in the project root directory. These files define your Magento installation and describe its dependencies. Configuration files specify, for example, that Magento uses MySQL, some PHP extensions, and Elasticsearch. (These are referred to as services.)

Five phases of deployment

Deployment consists of the following phases:

  1. Phase 1: Configuration validation and code retrieval
  2. Phase 2: Build
  3. Phase 3: Prepare slug
  4. Phase 4: Deploy slugs and cluster
  5. Phase 5: Deployment hooks
  6. Post-deployment: configure routing

Phase 1: Configuration validation and code retrieval

The remote server gets your code using Git. When you initially set up a project from a template, we retrieve the code from the the Magento ECE template.

The built-in Git server checks what you are pushing: if you have a syntax error in a configuration file, our Git server refuses the push.

Suppose you had a single MySQL database in your cluster and now you want two of those, or maybe you want to add an Elasticsearch instance. The built-in Git server detects this and verifies that the topology of your cluster is modified to your new needs.

This phase also runs composer install to retrieve dependencies.

Phase 2: Build

We build only what has changed since the last build. This is one of the things that make Magento Enterprise Cloud Edition so fast in deployment.

Magento Enterprise Cloud Edition builds the codebase. It runs hooks in the build section of .magento.app.yaml.

The default Magento build hook is a CLI command called magento-cloud:build. It does the following:

  • Applies patches located in vendor/magento/magento-cloud-configuration/patches, as well as optional project-specific patches in m2-hotfixes
  • Enables all extensions
  • Regenerates code and the dependency injection configuration (that is, the Magento var/generation and var/di directories) using bin/magento setup:di:compile.

It is important to note that at this point the cluster has not been created yet. So you should not try to connect to a database or imagine anything was daemonized.

But also know that once the application has been built it is going to be mounted on a read-only file system (you will be able to configure specific mount points that are going to be read/write).

This means you cannot FTP to the server and add modules. Instead, you must add code to your git repo and run git push, which builds and deploys the environment.

Phase 3: Prepare the slug

The result of the build phase is a read-only file system we refer to as a slug. In this phase, we create an archive and put it in permanent storage. The next time you push code, if a service did not change, you can use a slug from the archive.

It also means that reverting a deployment is basically instantaneous.

Phase 4: Deploy slugs and cluster

Now we provision your applications and all the backend services you need:

  • Mounts each service in its own container
  • Mounts the read-write file system is mounted on a highly available distributed storage grid
  • Configures the network so Magento’s services can “see” each other (and only each other)

The main file system is read-only. This is what guarantees we can do deterministic deployments. The read-only file system also dramatically improves your site's security because no process can write to the file system.

Phase 5: Deployment hooks

The last step runs a deployment script. You can use this for example to anonymize data in development environments, clear caches, ping external continuous integration tools, and so on.

When this script runs, you have access to all the services in your environment (Redis, database, and so on).

There are two default deploy hooks. One is pre-deploy.php, which does some necessary cleanup and retrieval of resources that were generated in the build hook. The second is bin/magento magento-cloud:deploy, which does the following

  • If Magento is not installed, it installs Magento with bin/magento setup:install, updates the deployment configuration, app/etc/env.php, and the database for your specified environment (for example, Redis and website URLs).

  • If Magento is installed, performs any necessary upgrades.

    The deployment script runs bin/magento setup:upgrade to update the database schema and data (which is necessary after extension or core code updates), and also updates the deployment configuration, app/etc/env.php, and the database for your environment.

    Finally, the deployment script and clears the Magento cache.

  • Sets the mode to either developer or production based on the environment variable APPLICATION_MODE.

    In production mode, the script optionally generates static web content using the command magento setup:static-content:deploy.

Our deploy script uses the values defined by configuration files in the .magento directory, then the script deletes the directory and its contents. Your local development environment isn't affected.

Post-deployment: configure routing

While the deployment is running, we freeze the incoming traffic at the entry point for 60 seconds. We are now ready to configure routing so your web traffic will arrive at your newly created cluster.