layout: default

group: cloud

subgroup: 01_welcome

title: Deployment process

menu_title: Deployment process

menu_order: 4

menu_node:

version: 2.2

github_link: cloud/discover-deploy.md

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.

If you are using external Bitbucket or 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.

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*.)

Deployment consists of the following phases:

1. [Phase 1: Configuration validation and code retrieval](#cloud-deploy-over-phases-conf)

2. [Phase 2: Build](#cloud-deploy-over-phases-build)

3. [Phase 3: Prepare slug](#cloud-deploy-over-phases-slug)

4. [Phase 4: Deploy slugs and cluster](#cloud-deploy-over-phases-slugclus)

5. [Phase 5: Deployment hooks](#cloud-deploy-over-phases-hook)

6. [Post-deployment: configure routing](#cloud-deploy-over-phases-route)

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](https://github.com/magento/magento-cloud){:target="_blank"}.

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.

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 modules

* Regenerates code and the dependency injection configuration (that is, the Magento `generated/code` and `generated/metadata` 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.

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.

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)

<div class="bs-callout bs-callout-info" id="info">

<p>The main file system is <em>read-only</em>. 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.</p>

</div>

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`]({{ page.baseurl }}install-gde/install/cli/install-cli-subcommands-db-upgr.html) to update the database schema and data (which is necessary after extension or core code updates), and also updates the [deployment configuration]({{ page.baseurl }}config-guide/config/config-php.html), `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`]({{ page.baseurl}}config-guide/bootstrap/magento-modes.html#mode-developer}}) or [`production`]({{ page.baseurl}}config-guide/bootstrap/magento-modes.html#mode-production) based on the environment variable [`APPLICATION_MODE`]({{ page.baseurl }}cloud/env/environment-vars_magento.html).

In `production` mode, the script optionally generates static web content using the command

[`magento setup:static-content:deploy`]({{ page.baseurl }}config-guide/cli/config-cli-subcommands-static-view.html).

<div class="bs-callout bs-callout-info" id="info">

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

</div>

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.

* [Get started with a project]({{page.baseurl}}cloud/project/project-start.html)

* [Get started with an environment]({{page.baseurl}}cloud/env/environments-start.html)

* [`.magento.app.yaml`]({{page.baseurl}}cloud/project/project-conf-files_magento-app.html)

* [`routes.yaml`]({{page.baseurl}}cloud/project/project-conf-files_routes.html)

* [`services.yaml`]({{page.baseurl}}cloud/project/project-conf-files_services.html)

layout: default

group: compman

subgroup: 28_cli-upgr

title: Command-line upgrade

menu_title: Command-line upgrade

menu_node: parent

menu_order: 1

version: 2.2

github_link: comp-mgr/cli/cli-upgrade.md

You can upgrade Magento from the command line if you installed the software using any of the following:

* Downloaded the metapackage using `composer create-project`

* Installed the compressed archive

<div class="bs-callout bs-callout-info" id="info">

<ul><li>If you cloned the Magento 2 GitHub repository, you <em>cannot</em> use this method to upgrade; instead, see <a href="{{page.baseurl}}install-gde/install/cli/dev_update-magento.html">Update the Magento application</a>.</li>

<li>If you configured Magento use use <code>pub</code> as its root directory, see the next section.</li>

<li>If you're upgrading to Magento 2.1 (including a Release Candidate) from Magento 2.0.7 or earlier <em>and</em> you installed sample data, see <a href="{{page.baseurl}}comp-mgr/cli/cli-rc1-samp.html">Command-line upgrade to Magento 2.1 with sample data</a> instead of this topic.</li></ul>

</div>

<div class="bs-callout bs-callout-warning">

<ul><li>If you're upgrading to version 2.1, see <a href="{{ page.baseurl }}release-notes/tech_bull_21-upgrade.html">Upgrade to Magento version 2.1 (June 22, 2016)</a>.</li>

<li>If you're upgrading from Magento CE or EE 2.0.0 or 2.0.1, you must first perform the tasks discussed in the <a href="{{page.baseurl}}release-notes/tech_bull_201-upgrade.html">Technical Bulletin (1/28/16)</a>.</li></ul>

</div>

This section applies to you *only* if you set the Magento root directory to `<your Magento install dir>/pub`. If you did not do this, skip this section and continue with the next section.

{% collapsible If you use pub as your Magento root directory: %}

* For the upgrade, create another subdomain or docroot that uses the Magento installation directory as its root.

Run the [System Upgrade utility]({{page.baseurl}}comp-mgr/upgrader/upgrade-start.html) using that subdomain.

* Use the [following procedure](#upgrade-cli-upgr) to upgrade Magento using the command line.

{% endcollapsible %}

To prevent access to your store while it's being upgraded, put your store in maintenance mode.

<div class="bs-callout bs-callout-info" id="info">

<p>You can optionally create a <a href="{{page.baseurl}}comp-mgr/trouble/cman/maint-mode.html">custom maintenance mode page</a>.</p>

</div>

{% collapsible To enable maintenance mode: %}

1. Log in to your Magento server as, or switch to, the Magento file system owner.

2. Enter the following command:

php <your Magento install dir>/bin/magento maintenance:enable

For additional options, see [Enable or disable maintenance mode]({{page.baseurl}}install-gde/install/cli/install-cli-subcommands-maint.html).

{% endcollapsible %}

{% collapsible To upgrade using the command line: %}

1. Log in to your Magento server as, or switch to, the Magento file system owner.

2. Change to the directory in which you installed the Magento software.

For example, `cd /var/www/html/magento2`

2. Enter the following commands in the order shown:

composer require <product> <version> --no-update

composer update

For example, to upgrade to Magento CE version 2.0.11, enter:

composer require magento/product-community-edition 2.0.11 --no-update

composer update

To upgrade to Magento EE version 2.0.11, enter:

composer require magento/product-enterprise-edition 2.0.11 --no-update

composer update

<div class="bs-callout bs-callout-info" id="info">

<p>If an error displays about a missing <code>.gitignore</code> files, see the <a href="{{page.baseurl}}release-notes/tech_bull_201-upgrade.html#resolution2">Technical Bulletin (1/28/16)</a>.</p>

</div>

3. If prompted, enter your [authentication keys]({{page.baseurl}}comp-mgr/prereq/prereq_auth-token.html).

4. Manually clear `var` subdirectories:

rm -rf <Magento install dir>/var/cache/*

rm -rf <Magento install dir>/var/page_cache/*

rm -rf <Magento install dir>/generated/code/*

4. Update the database schema and data:

php bin/magento setup:upgrade

5. Restart Varnish if you use it for page caching.

service varnish restart

6. Access your storefront.

The following error might display:

We're sorry, an error has occurred while generating this email.

If so, perform the following tasks:

1. Reset [file system ownership and permissions]({{page.baseurl}}install-gde/prereq/file-system-perms.html) as a user with `root` privileges.

2. Clear the following directories and try again:

<your Magento install dir>/var/cache

<your Magento install dir>/var/page_cache

<your Magento install dir>/generated/code

{% endcollapsible %}

/var/www/html/magento2/generated/code/Composer

/var/www/html/magento2/generated/code/Magento

/var/www/html/magento2/generated/code/Symfony

The directory '/var/www/html/magento2/generated/metadata/' doesn't exist - skipping cleanup

layout: default

group: compman

subgroup: 32_UseUpgrade

title: Step 4. Upgrade

menu_title: Step 4. Upgrade

menu_node:

menu_order: 20

version: 2.2

github_link: comp-mgr/upgrader/upgrade.md

The components you're upgrading display. The following figure shows an example.

<img src="{{ site.baseurl }}common/images/upgr_upgrade.png" width="550px" alt="Click upgrade to complete the task">

To complete the upgrade, click **Upgrade**. If the upgrade is successful, a page similar to the following displays.

<img src="{{ site.baseurl }}common/images/upgr_success.png" width="350px" alt="Your upgrade was successful">

Messages similar to the following display in the Console Log:

{% collapsible Click to view the Console Log %}

<img src="{{ site.baseurl }}common/images/upgrade-success-consolelog.png" width="650px">

{% endcollapsible %}

After the upgrade completes, manually clear `var` subdirectories:

rm -rf <Magento install dir>/var/cache/*

rm -rf <Magento install dir>/var/page_cache/*

rm -rf <Magento install dir>/generated/code/*

After the upgrade completes, restart Varnish if you use it for page caching.

service varnish restart

Then access your storefront and verify everything is working properly.

After you finish your upgrade, errors might display.

* On the main storefront page, the following error might display.

We're sorry, an error has occurred while generating this email.

* On a category page, the following error might display:

We can't find products matching the selection.

If any of the preceding errors display, perform all of the following tasks.

{% include install/sampledata/file-sys-perms-digest.md %}

Clear the `var/cache`, `var/page_cache`, `generated/code`

A sample command follows:

rm -rf var/cache/* var/page_cache/* generated/code/*

After performing the preceding tasks, access your storefront again. If necessary, press Control+R to force the page to reload.