Magento 2 Deployment Process – Step-by-Step Guide

I have set up a structure at our agency that allows us to use Composer to deploy all our Magento sites. This might be a bit of overkill for the question you asked but here's a basic overview of the structure anyway:

Repository structure

Below is the folder structure of the 'parent' repository. It contains the composer JSON and lock files and other configuration required for deployment.

- code
   - magento
- deployment
- environmental
   - local
       - local.xml
       - robots.txt
   - staging
       - local.xml
       - robots.txt
   - production
       - local.xml
       - robots.txt
- provisioning
- public
   - index.php
- vendor
- composer.json
- composer.lock

• All client-specific customisations are stored in a separate "customisations" module that gets installed using Composer
• The Magento core is included as a Git submodule (code/magento)
• A custom index.php and other folders like media and errors sit inside a public folder outside of the Magento root
• Environment specific files (local.xml, robots.txt, etc) get symlinked into the Magento root during the deployment process
• The vendor folder is excluded from Git, but the composer.lock file is included.

Deployment

• We deploy using Capsitrano which allows for multiple app servers and environments (staging/production)
• Capistrano builds the entire codebase on the server in a new folder, and then swaps the webroot symlink at the very end meaning there is no downtime for your website.
• Capistrano runs composer install during the build and deploys all modules into the Magento submodule.

This is still not a continuous integration setup but I find it works well for Magento sites. Feel free to send me a message if you'd like some more advice that's specific to your setup.

In fact, every day I am less convinced about the utility of Magento 2 production mode, unless you are not going to change anything in the project. Can you change my mind?

I'm not sure if I understand you correct, but that's exactly what the production mode is for: production systems where you do not change anything (code wise). Until the next deployment, that is.

I find the Git based deployment that you are using less suitable for Magento 2 than it was for Magento 1, because of all the preprocessing. The build and deployment is more complex and IMHO there is no way around an automated build process

What I would recommend:

• Have repeatable deployments, i.e. you should be sure that the exact same code ends up in production that was in staging, including generated files.

• To achieve that, separate build from deployment and do the following in the build process:

  • composer install (adding vendor to the repository instead is possible too, but if you did that just to avoid running composer on the server during deployment, rather do it in the build step and only keep composer.lock in the repo)

  • Code generation (YMMV):

    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy
    

  • create an archive (the build artifact) from the full Magento directory, excluding media and var, but including vendor, pub, var/generated and var/di. Starting with magento-2.2, var/generated and var/di are moved to generated/code and generated/metadata, which makes it easier to separate them from the rest of var which should be ignored for deployments.

• In the deployment, copy the build artifact to the target server, extract it to a new directory and:

  • link persistent directories into it (media, var/session, var/log, ...)
  • enable maintenance mode
  • switch document root (usually the docroot is a symlink to the last release, change it to the new release)
  • flush cache
  • run setup:upgrade
  • disable maintenance mode

• This deployment process can be easily implemented with Deployer, which is like Capistrano but in PHP. A full deployment solution for Magento 2 based on deployer can be found here: https://github.com/mwr/magedeploy2 (thanks to netz98!) and here is another one that we use: https://github.com/staempfli/magento2-deployment-tool

• Keeping app/etc/config.php in the repository is good to keep track of enabled and disabled modules.

This is not a step by step instruction but it should give you an overview for a more robust alternative to your current process. Take a look at the linked tools to see how a full solution may look like.