Build and deploy on local

Before pushing your code to Staging or Production, you should fully build on your local. Fully testing builds and deploys along with full site testing can reduce the risk of issues or delays for your final site deployment, and expose any issues early for debugging.

These tasks walk through:

  • Complete development on your local
  • Complete a full build and deploy process on your local (deploys to the associated active Integration environment)
  • Test fully before continuing deployment to Staging

For more information on the full five step process, see the Deployment process.

We highly recommend completing your testing in an Integration active environment and the Staging environment. Only complete final tests for going live in the Production environment. Your Staging environment is best for testing with code, data, and services including Fastly, New Relic, and others.

Update composer if you add extensions

If you modified your composer.json to add modules, we recommend running the composer update command in a terminal. This command updates any dependencies in the composer.lock. During the build phase, we run composer install on a fresh clone of your Git branch of code to retrieve the latest dependencies.

Push code to Git and Cloud

Before you continue, make sure you push all current code to the remote Cloud server so that, in event of issues, you can recover the state of the Magento application.

To prepare your code and branch:

  1. Log in to your local development system, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access.
  3. Enter the following command in a terminal to log in to your project:

    magento-cloud login
    
  4. List your projects. With the project ID, you can complete additional commands.

    magento-cloud project:list
    
  5. If necessary, clone the project to your local. You should have cloned when setting up your local development workspace.

    magento-cloud project:get <project ID>
    
  6. Change to a project directory. For example, cd /var/www/html/magento2
  7. List environments in the project. Every environment includes an active Git branch of your code, database, environment variables, configurations, and services.

    magento-cloud environment:list
    

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list to see the full list.

  8. Fetch origin branches to get the latest code:

    git fetch origin
    
  9. Check out, or switch to, a specific branch and environment. Git commands only checkout the Git branch. The Magento Cloud command also switches to the active environment.

    magento-cloud environment:checkout <environment ID>
    

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull any updated code to your local for the environment ID (which is the Git branch):

    git pull origin <environment ID>
    
  11. Create a snapshot of the environment as a backup:

    magento-cloud snapshot:create -e <environment ID>
    

To push code to your remote environment:

  1. If you haven’t already, change to your project root directory.
  2. Enter the following commands to complete code commits in a terminal:

    git add -A && git commit -m "<comment>"
    git push origin <branch name>
    
  3. The build and deploy phases begin. Wait for the deployment to complete.

Build phase

During the build phase, we perform the following tasks:

  • Apply patches distributed to all Magento Commerce (Cloud) accounts
  • Apply patches we provided specifically to you
  • Enable all modules to build
  • Compile code and the dependency injection configuration

The build also checks for a configuration file. If the file exists, the static file deployment is also completed during the build stage. If not, it’s completed in the deployment stage.

Before you continue, you must know the file system path to any patch we provided specifically to you. Typically, hot fixes are in the <Magento root dir>/m2-hotfixes directory.

To build your site:

  1. Apply patches distributed to all Magento Commerce (Cloud) accounts.

    Enter the following command from the project root directory:

    php vendor/magento/magento-cloud-configuration/patch.php
    

    Output includes the following:

    [2016-11-30 15:05:15] Copying static.php to front-static.php
    [2016-11-30 15:05:15] Command:git apply /var/www/html/magento2/vendor/magento/magento-cloud-configuration/patches/000-MAGETWO-57719-2.1.2.patch
    [2016-11-30 15:05:15] Status:0
    [2016-11-30 15:05:15] Output:array (
    )
    [2016-11-30 15:05:15] Command:git apply /var/www/html/magento2/vendor/magento/magento-cloud-configuration/patches/MAGETWO-52660-scd-improvement.patch
    [2016-11-30 15:05:15] Status:0
    [2016-11-30 15:05:15] Output:array (
    )
    
    ... more ...
                        )
    
  2. Apply hot fixes and other patches provided to you:

    git apply <path to patch>
    

    For example, to apply hot fixes:

    git apply m2-hotfixes/<patch file name>
    

    If the m2-hotfixes directory is empty, skip this step.

    If patches are present, output from this command is similar to the patches command.

  3. Enable all modules:

    php bin/magento module:enable --all
    
  4. Compile code and the dependency injection configuration:

    php bin/magento  setup:di:compile
    

    This command can take several minutes to complete.

    Messages similar to the following are displayed:

    Compilation was started.
    0% 1 sec 54.0 MiB%message% 0/7 [>---------------------------]
    0% 1 sec 54.0 MiBProxies code generation...
    0/7 [>---------------------------]
    0% 1 sec 54.0 MiB
    Proxies code generation... 1/7 [====>-----------------------]  14% 1 sec 58.0 MiB
    Repositories code generation... 1/7 [====>-----------------------]  14% 1 sec 58.0 MiB
    Repositories code generation... 2/7 [========>-------------------]  28% 30 secs 176.0 MiB
    
    ... more ...
    Interception cache generation... 7/7 [============================] 100% 5 mins 324.0 MiB
    

If errors display, debug them if possible or open a support ticket to get additional assistance.

We strongly recommend you do all your testing in an integration or staging environment only, and not in production.

Deploy phase

We highly recommend having Magento already installed prior to deployment. During the deployment phase, we perform the following tasks:

  • Install the Magento application if needed
  • If the Magento application is installed, upgrade components
  • Clear the cache
  • Set the Magento application for production mode

To deploy your site:

  1. If you haven’t already, log in as or switch to the Magento file system owner.
  2. Change to your project root directory.
  3. Enter the following command:

    php bin/magento setup:upgrade
    

    We highly recommend having Magento already installed if you followed the First time deployment. If you haven’t installed the Magento application yet, use the magento setup:install command instead. Be advised, you may encounter issues with enabled modules on a fresh installation.

  4. Clean the Magento cache:

    php bin/magento cache:clean
    
  5. Set the Magento application for production mode:

    php bin/magento deploy:mode:set production
    

If errors display, debug them if possible or open a support ticket to get additional assistance.

Next step

Prepare to deploy to Staging and Production