2. Local Environment.md

Local Environment

2.1 Demonstrate ability to set up local development*

Software you need to have locally for developing a Magento Cloud project

• Operating system: Debian GNU/Linux 8 (jessie)
• Virtual machine or container (host): Vagrant, Docker
• Git
• Composer
• Web server: Apache, Nginx
• PHP: PHP 7.1.3+ or 7.2
• PHP packages: bcmath, curl, ext-dom, fpm, gd, intl, json, mbstring, mcrypt (for PHP 7.1 and earlier only), mysql, xml, zip
• Set up PHP memory limit (memory_limit: 2G)
• Database: MySQL or MariaDB with a Galera Cluster (Magento Commerce environments use it)

  for Pro plans modify the auto_increment_increment = 3 value

• Magento Cloud CLI
• SSH
• Bash or Cygwin or Git Bash (for windows)

Optional:

• Redis
• RabbitMQ
• Varnish
• ElasticSearch

Se also Magento Commerce requirements

2.2 Given a scenario, demonstrate ability to use the Magento-cloud CLI tool

Install Magento-cloud CLI. Retrieve project info

• Log in to your local development machine or switch to the Magento file system owner
• Change to a directory to which the Magento file system owner has write access, such as the home directory
• Install: curl -sS https://accounts.magento.cloud/cli/installer | php
• Run: source $HOME/.bashrc or export PATH=$PATH:$HOME/.magento-cloud/bin
• Verify: magento-cloud list

Manage project and environments

Clone and branch the project:

• Log in to the Magento Cloud CLI: magento-cloud login
• List your projects: magento-cloud project:list
• Clone a project: magento-cloud project:get <project-ID>
• Change to the magento2 directory
• List available environments for the project: magento-cloud environment:list
• Fetch the remote branches: git fetch magento
• Pull updated code: git pull magento <environment-ID>

Change the Magento ADMIN variables:

• View existing variables: magento-cloud variables
• Set a variable: magento-cloud vset <variable-name> <variable-value>
• Set next variables: ADMIN_EMAIL, ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_URL

Other:

• Redeploy: git commit --allow-empty -m "redeploy" && git push <branch-name>
• Clone a project to a directory: magento-cloud project:get <project-ID> <directory> -e <environment-ID>
• Create a new branch with a name and an ID: magento-cloud environment:branch <name> <parent-branch>
• Check out an existing environment: magento-cloud environment:checkout <environment-ID>
• Merge changes in this environment with its parent: magento-cloud environment:merge -p <project-ID> -e <environment ID>
• Synchronize (git pull) code and data from the parent to this environment: magento-cloud environment:synchronize -p <project-ID> -e <environment-ID> {code|data}
• Delete more than one environment: magento-cloud environment:delete <environment-1-ID> <environment-2-ID>
• Tunnels: magento-cloud tunnel:list and magento-cloud tunnel:open -e <environment ID> --app mymagento and magento-cloud tunnel:info -e <environment ID>

Connect to database and SSH

• SSH: magento-cloud environment:ssh
• Get DB creds: php -r 'print_r(json_decode(base64_decode($_ENV["MAGENTO_CLOUD_RELATIONSHIPS"]))->database);' or echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp
• Connect to database mysql --host=127.0.0.1 --user='<database username>' --pass='<user password>' --database='<name>' --port='<port>'

Build the project locally

Build via Magento Cloud CLI: magento-cloud local:build

Via docker: docker-compose run build cloud-build cloud-build

#!/bin/bash

composer --working-dir=$MAGENTO_ROOT install --no-suggest --no-ansi --no-interaction --no-progress --prefer-dist

echo "Building Magento Cloud..."
./$MAGENTO_ROOT/vendor/bin/ece-tools build

echo "Fixing file permissions..."

find $MAGENTO_ROOT/pub -type f -exec chmod 664 {} \;
find $MAGENTO_ROOT/pub -type d -exec chmod 775 {} \;

echo "Building complete"

Magento Cloud CLI / local:build

Description: Build the current project locally

Usage:
 magento-cloud build [-a|--abslinks] [-s|--source SOURCE] [-d|--destination DESTINATION] [-c|--copy] [--clone] [--run-deploy-hooks] [--no-clean] [--no-archive] [--no-backup] [--no-cache] [--no-build-hooks] [--no-deps] [--working-copy] [--concurrency CONCURRENCY] [--lock] [--] [<app>]...

Arguments:
  app                            Specify application(s) to build

Options:
  -a, --abslinks                 Use absolute links
  -s, --source=SOURCE            The source directory. Defaults to the current project root.
  -d, --destination=DESTINATION  The destination, to which the web root of each app will be symlinked. Default: _www
  -c, --copy                     Copy to a build directory, instead of symlinking from the source
      --clone                    Use Git to clone the current HEAD to the build directory
      --run-deploy-hooks         Run deploy and/or post_deploy hooks
      --no-clean                 Do not remove old builds
      --no-archive               Do not create or use a build archive
      --no-backup                Do not back up the previous build
      --no-cache                 Disable caching
      --no-build-hooks           Do not run post-build hooks
      --no-deps                  Do not install build dependencies locally
      --working-copy             Drush: use git to clone a repository of each Drupal module rather than simply
                                 downloading a version
      --concurrency=CONCURRENCY  Drush: set the number of concurrent projects that will be processed at the same
                                 time [default: 4]
      --lock                     Drush: create or update a lock file (only available with Drush version 7+)
  -h, --help                     Display this help message
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
  -y, --yes                      Answer "yes" to all prompts; disable interaction
  -n, --no                       Answer "no" to all prompts
  -v|vv|vvv, --verbose           Increase the verbosity of messages

Examples:
 Build the current project:
   magento-cloud build

 Build the app "example" without symlinking the source files:
   magento-cloud build example --copy

 Rebuild the current project without using an archive:
   magento-cloud build --no-archive

Magento Cloud CLI 1.24.0

Global options:
  --help           -h Display this help message
  --quiet          -q Do not output any message
  --verbose        -v|vv|vvv Increase the verbosity of messages
  --version        -V Display this application version
  --yes            -y Answer "yes" to all prompts; disable interaction
  --no             -n Answer "no" to all prompts

Available commands:
  clear-cache (clearcache, cc)                   Clear the CLI cache
  docs                                           Open the online documentation
  help                                           Displays help for a command
  list                                           Lists commands
  multi                                          Execute a command on multiple projects
  web                                            Open the Web UI
activity
  activity:get                                   View detailed information on a single activity
  activity:list (activities, act)                Get a list of activities for an environment or project
  activity:log                                   Display the log for an activity
app
  app:config-get                                 View the configuration of an app
  app:list (apps)                                List apps in the project
auth
  auth:browser-login (login)                     Log in to Magento Cloud via a browser
  auth:info                                      Display your account information
  auth:logout (logout)                           Log out of Magento Cloud
  auth:password-login                            Log in to Magento Cloud using a username and password
blackfire
  blackfire:setup                                Setup Blackfire.io integration for the project
certificate
  certificate:add                                Add an SSL certificate to the project
  certificate:delete                             Delete a certificate from the project
  certificate:get                                View a certificate
  certificate:list (certificates, certs)         List project certificates
commit
  commit:get                                     Show commit details
  commit:list (commits)                          List commits
db
  db:dump                                        Create a local dump of the remote database
  db:size                                        Estimate the disk usage of a database
  db:sql (sql)                                   Run SQL on the remote database
domain
  domain:add                                     Add a new domain to the project
  domain:delete                                  Delete a domain from the project
  domain:get                                     Show detailed information for a domain
  domain:list (domains)                          Get a list of all domains
  domain:update                                  Update a domain
environment
  environment:activate                           Activate an environment
  environment:branch (branch)                    Branch an environment
  environment:checkout (checkout)                Check out an environment
  environment:delete                             Delete an environment
  environment:http-access (httpaccess)           Update HTTP access settings for an environment
  environment:info                               Read or set properties for an environment
  environment:list (environments, env)           Get a list of environments
  environment:logs (log)                         Read an environment's logs
  environment:merge (merge)                      Merge an environment
  environment:push (push)                        Push code to an environment
  environment:redeploy (redeploy)                Redeploy an environment
  environment:relationships (relationships)      Show an environment's relationships
  environment:ssh (ssh)                          SSH to the current environment
  environment:synchronize (sync)                 Synchronize an environment's code and/or data from its parent
  environment:url (url)                          Get the public URLs of an environment
integration
  integration:add                                Add an integration to the project
  integration:delete                             Delete an integration from a project
  integration:get                                View details of an integration
  integration:list (integrations)                View a list of project integration(s)
  integration:update                             Update an integration
  integration:validate                           Validate an existing integration
local
  local:build (build)                            Build the current project locally
  local:dir (dir)                                Find the local project root
mount
  mount:download                                 Download files from a mount, using rsync
  mount:list (mounts)                            Get a list of mounts
  mount:size                                     Check the disk usage of mounts
  mount:upload                                   Upload files to a mount, using rsync
project
  project:clear-build-cache                      Clear a project's build cache
  project:get (get)                              Clone a project locally
  project:info                                   Read or set properties for a project
  project:list (projects, pro)                   Get a list of all active projects
  project:set-remote                             Set the remote project for the current Git repository
repo
  repo:cat                                       Read a file in the project repository
  repo:ls                                        List files in the project repository
route
  route:get                                      View a resolved route
  route:list (routes)                            List all routes for an environment
self
  self:install                                   Install or update CLI configuration files
  self:update (self-update)                      Update the CLI to the latest version
service
  service:list (services)                        List services in the project
  service:mongo:dump (mongodump)                 Create a binary archive dump of data from MongoDB
  service:mongo:export (mongoexport)             Export data from MongoDB
  service:mongo:restore (mongorestore)           Restore a binary archive dump of data into MongoDB
  service:mongo:shell (mongo)                    Use the MongoDB shell
  service:redis-cli (redis)                      Access the Redis CLI
snapshot
  snapshot:create                                Make a snapshot of an environment
  snapshot:list (snapshots)                      List available snapshots of an environment
  snapshot:restore                               Restore an environment snapshot
ssh-key
  ssh-key:add                                    Add a new SSH key
  ssh-key:delete                                 Delete an SSH key
  ssh-key:list (ssh-keys)                        Get a list of SSH keys in your account
tunnel
  tunnel:close                                   Close SSH tunnels
  tunnel:info                                    View relationship info for SSH tunnels
  tunnel:list (tunnels)                          List SSH tunnels
  tunnel:open                                    Open SSH tunnels to an app's relationships
  tunnel:single                                  Open a single SSH tunnel to an app relationship
user
  user:add                                       Add a user to the project
  user:delete                                    Delete a user from the project
  user:get                                       View a user's role(s)
  user:list (users)                              List project users
  user:update                                    Update user role(s) on a project
variable
  variable:create                                Create a variable
  variable:delete                                Delete a variable
  variable:get (vget)                            View a variable
  variable:list (variables, var)                 List variables
  variable:update                                Update a variable
worker
  worker:list (workers)                          Get a list of all deployed workers

2.x Docker

Magento Commerce (Cloud) Docker

Docker images:

• DB: MariaDB versions 10.0, 10.1, 10.2
• FPM: PHP versions 7.0, 7.1, 7.2
• NGINX: 1.9
• Redis: 3.0, 3.2, 4.0, 5.0
• Varnish: 4.x
• RabbitMQ: 3.5, 3.7
• Elasticsearch: 1.7, 2.4, 5.2, 6.5

Launch Docker configuration:

• Docker configuration generator: ./vendor/bin/ece-tools docker:build
• Copy and configure env files:

  cp docker/config.php.dist docker/config.php
  cp docker/global.php.dist docker/global.php
  

• Convert the PHP configuration files to Docker ENV files: ./vendor/bin/ece-tools docker:config:convert
• Build files to containers and run in the background: docker-compose up -d
• Build Magento in the Docker container: docker-compose run build cloud-build
• Deploy Magento in the Docker container: docker-compose run deploy cloud-deploy
• Stop and remove: docker-compose down -v

ece-tools

 docker
  docker:build              Build docker configuration
  docker:build:integration  Build test docker configuration
  docker:config:convert     Convert raw config to .env files configuration

Cli containers:

build—extends the CLI container to perform operations with writable filesystem, similar to the build phase

deploy—extends the CLI container to use read-only file system, similar to the deploy phase

cron—extends the CLI container to run cron

The setup:cron:run and cron:update commands are not available on Cloud and Docker for Cloud environment

Cron only works with CLI container to run ./bin/magento cron:run command (https://devdocs.magento.com/guides/v2.3/cloud/docker/docker-development.html)

Docker compose command:

Build environment    docker-compose run build cloud-build
Deploy environment    docker-compose run deploy cloud-deploy
Connect to CLI container    docker-compose run deploy bash
Use ece-tools command    docker-compose run deploy ece-command <command>
Use Magento command    docker-compose run deploy magento <command>
Stop Docker environment without destroying containers    docker-compose stop
Resume Docker environment    docker-compose start

Documentation:

• Local development
• Prepare for local environment setup
• Docker development environment