Example README.md file for Magento 2 project

README.md

Title of Site

Developer Setup

Run through the following steps to setup this project on your local environment. These instructions assume you're using the standard Classy Llama devenv.

Server Access

Use the following to connect to stage.

ssh www-stage@stage.example.com

Server Setup

The Rackspace server consists of three servers:

• Web Server 1
  • Handles the admin.example.com site, prod CRON jobs, as well as all of the stage sites
    • All of the stage urls (e.g., https://stage.example.com/, https://m2stage.example.com/, etc) as well as the production admin url (https://admin.example.com/backend) point to this server
  • IP: 100.100.100.214
• Web Server 2
  • Handles the frontend production traffic
    • All of the production frontend urls (e.g., https://www.example.com, https://www.example.com, https://example.example.com, etc) will be configured to point to this server
  • IP: 100.100.100.215
• DB Server
  • Both prod and stage DBs are hosted on this server. This server is not accessible from the web and is only accessible from the two web servers.
  • Hostname: gds-db-master
  • IP: 100.100.100.213

Server Error Logs

Stage

For Magento internal errors, run these commands and then reproduce issue:

ssh www-stage@stage.example.com
tail -fn0 /var/www/stage/current/var/log/*.log

For server errors (500, etc) run these commands and then reproduce issue:

ssh www-stage@stage.example.com
tail -fn0 /var/log/php-fpm/www-stage-error.log /var/log/nginx/*error*.log

To see errors on pages that list an error number at the bottom of the page:

ssh www-stage@stage.example.com
cat /var/www/stage/current/var/report/<REPORT NUMBER>

Prod

For Magento internal errors, run these commands and then reproduce issue (connect to whichever server is relevant to what you're doing):

# This is the server that runs the admin and CRON jobs
ssh www-prod@100.100.100.214
# This is the server that runs the frontend traffic
ssh www-prod@100.100.100.215
tail -fn0 /var/www/prod/current/var/log/*.log

For server errors (500, etc) run these commands and then reproduce issue (connect to whichever server is relevant to what you're doing):

# This is the server that runs the admin and CRON jobs
ssh www-prod@100.100.100.214
# This is the server that runs the frontend traffic
ssh www-prod@100.100.100.215
tail -fn0 /var/log/php-fpm/www-prod-error.log /var/log/nginx/*error*.log

To see errors on pages that list an error number at the bottom of the page:

ssh www-prod@100.100.100.215
cat /var/www/prod/current/var/report/<REPORT NUMBER>

The production admin can be accessed by this url (without setting up a hosts record): admin.example.com

Initial Project Setup

1. Install application from within VM:

    cd /var/www/sites/
    mkdir example.dev/
    cd example.dev
    git clone -b develop git@bitbucket.org:classyllama/example-m2.git ./
    ln -s env.php.dev app/etc/env.php
    composer install
    chmod +x bin/magento
   

   The ln -s env.php.dev app/etc/env.php command above is optional. Some developers would prefer to make changes to their env.php file that they don't want to track in source control (for example, using a different DB host or DB name like example_dev2). For those developers, they should run this command instead: cp app/etc/env.php.dev app/etc/env.php. The Tech Lead on this project will do their best to notify developers when changes are made to env.php.dev that should be included in all env.php files.

   1. Since this site uses Git submodule(s), run this command:

       cd /var/www/sites/example.dev
       git submodule init
       git submodule update
      

2. Configure your session storage as described in "Session Storage".

3. Add the following entry to your /etc/hosts file:

    10.19.89.14 example.dev
   

4. Update vhost configuration.

Sync Database From Stage

Run these commands from within your VM any time you need to sync the stage database to your local environment. Run these commands from within the project directory.

# Create database
mysql -e "DROP DATABASE IF EXISTS example_dev;"
mysql -e "CREATE DATABASE IF NOT EXISTS example_dev;"

# Dump DB
# Note: change STRIP_FLAG variable (or don't set it) if you need customer/sales data (e.g., @stripped)
STRIP_FLAG='@idx @log @trade @search catalog_product_index_eav_replica catalog_product_index_price_replica'
DUMP_FILENAME=example_stage_$(date +%F).sql.tgz
ssh -C www-stage@stage.example.com "mr --root-dir=/var/www/stage/current db:dump --stdout --strip="'$STRIP_FLAG'" | gzip" | \
pv > /tmp/$DUMP_FILENAME


# Import DB
pv /tmp/$DUMP_FILENAME | gunzip | mysql example_dev;
rm /tmp/$DUMP_FILENAME;

# Update base urls
mr db:query 'UPDATE core_config_data SET `value` = REPLACE(VALUE, "://www.", "://") WHERE `path` LIKE "web%url";'
mr db:query 'UPDATE core_config_data SET `value` = REPLACE(VALUE, "://stage.", "://") WHERE `path` LIKE "web%url";'
mr db:query 'UPDATE core_config_data SET `value` = REPLACE(VALUE, ".com", ".dev") WHERE `path` LIKE "web%url";'


# Flush cache, upgrade DB, reindex
cd /var/www/sites/example.dev
bin/magento cache:flush
bin/magento cache:clean
bin/magento setup:db-schema:upgrade
bin/magento setup:db-data:upgrade
bin/magento indexer:reindex

Sync Media From Stage

rsync -avz --exclude=catalog/product/cache \
    www-stage@stage.example.com:/var/www/stage/current/pub/media/ /var/www/sites/example.dev/pub/media/

Sync Database From Prod

Reference the commands above and edit for usage on prod. Generally, syncing should be done from stage, not prod.

Sync Media From Prod

rsync -avz --exclude=catalog/product/cache \
    www-prod@admin.example.com:/var/www/prod/current/pub/media/ /var/www/sites/example.dev/pub/media/