Skip to content


Magento 1 Exploratory Upgrade Procedure

This assumes the Magento 1 codebase already exists in a git repository, with the webroot in a "public" subfolder

Check for core amends

  1. Download a copy of the plain Magento 1 version matching the current site
  2. Patch the plain Magento 1 to the same level as the current site (look at current Magento app/etc/applied.patches.list and apply the same patches to plain Magento 1)
  3. Use a diffing tool (Meld for GUIs, diff for command line, or DiffMerge which allows to export differences) to check for any modified files in these paths:
    • app/code/core/
    • app/code/local/Mage - check for Mage core local overrides in this directory.
    • app/design/adminhtml/default/default/
    • app/design/frontend/base/default/
    • js/
    • lib/
    • shell/
    • skin/frontend/base/default/
    • skin/adminhtml/default/default/
  4. If there are modified files in any of these, document what they are as you'll need to decide what to do with these (Ideally create Epic in Jira and export diff changes using DiffMerge)

Replace the Magento code


  • Copy existing staging.{client-name}.conf, and rename it to preupgrade-staging.{client-name}.conf, change root accordingly.
  • Prepend all string staging occurrences to preupgrade-
  • Duplicate your /etc/vhosts staging entry, and prepend it with preupgrade- also.
  • Restart nginx
  • Rename your old database to {something}_preupgrade
  • Copy preupgrade database and rename it to {something}_postupgrade
  • Update core_config_data base_url to match correct vhosts
  • Check if both preupgrade and staging (postupgrade) are still available.

  • Check out a new branch with git checkout -b magento-1.x.x.x-upgrade on your old staging web root.

  • Move the entire public folder (be sure to remember to include hidden files) to a location outside the git repo, ideally that location is matched by newly created preupgrade vhost, so you can access the site. (We already did this step when creating vhost therefore public folder is backed up and can be removed).
  • Extract the target Magento code to the git repo's public folder
  • Set correct file permissions

Container only

find . -type f -exec chmod 660 {} \;
find . -type d -exec chmod 770 {} \; 
chown -R ec:nginx /var/vhosts/www/{yourhost}/

For production environment use proper permissions from here


Also it's good to debug file access as nginx user. Though, you can simple login as nginx user, you need to user the line below su -s /bin/bash nginx. But you need to do that from within root.

Reinstate the site's modifications

  1. Copy from the old public folder anything that exists in the old folder and not the new one in:
    • app/design/frontend/ - these are their design packages
    • app/code/local/
    • app/code/community/
    • app/design/adminhtml/default/default/layout/
    • app/design/adminhtml/default/default/template/
    • app/design/frontend/base/default/layout/
    • app/design/frontend/base/default/template/
    • app/etc/modules/
    • js/
    • lib/
    • media/
    • shell/
    • skin/frontend/ - these are their design skins
    • skin/frontend/base/default/css/
    • skin/frontend/base/default/js/
    • skin/frontend/base/default/images/
    • skin/adminhtml/base/default/css/
    • skin/adminhtml/base/default/js/
    • skin/adminhtml/base/default/images/
  2. Check for anything you might have missed in git status's output
  3. If you're happy everything in git status is as a result of Magento's code having changed, then git add and commit everything as having upgraded the Magento version

Perform database migrations

  1. Trigger the database migrations by either hitting index.php, or using magerun. Remember to have caches disabled
  2. You might see things going wrong. This is the reason to do an exploratory upgrade. Document anything you have to do to get it to load a homepage

Smoke test the site

  1. Click around the site and the admin
  2. Fix anything that blocks testing of the site
  3. Document anything you do to make it work
  4. git commit any fixes, and publish it to a staging site for testing