The Ultimate Guide to Installing Magento Extensions
Welcome
I have seen lots of successful installs and some not so successful ones. This guide distills my recommendations learned from supporting over 50,000 downloads of my extensions into easy to follow steps.
The guide comes in two flavours, depending on your experience (and risk
appetite): the recommended version with a safety net, and an abbreviated fast version for experienced Magento users. You will find an explanation of each step in the 'Steps' section of this guide.
Summary – Recommended Installation:
1. Turn off Magento's Compilation Mode (if you have previously enabled it) 2. Verify your site is working correctly
3. Backup your Magento files
4. Turn on Magento maintenance mode 5. Create a database backup
6. Turn on Magento's Cache 7. Install the extension
8. Refresh the Magento Cache
9. Log out of your backend and then log back in
10. Verify that your site and new extension are working correctly 11. Turn off Magento maintenance mode
12. Rerun Magento's compilation process before turning it back on (if you are using it)
13. Backup your Magento files and create another database backup (optional) 14. Repeat steps 1-13 for your live site
Note: The best piece of advice I can offer is to perform a test installation of any new extension on a test site (using steps 1-13 above), prior to adding it to your live site (repeating steps 1-13 on the live site). A test site, based on a copy of your current live store, can be used to test new settings or extension
installations, making sure you are 100% happy with the outcome before allowing the changes to go live. Distributed version control systems (such as mercurial and git) can be used to sync live and test sites with minimal effort.
Summary - The Fast Version (aka “The Thrill-Seeker Guide”): This is an abbreviated version of the recommended installation:
1. Turn off Magento's Compilation Mode (if you have previously enabled it) 6. Turn on Magento's Cache
7. Install the extension
8. Refresh the Magento Cache
9. Log out of your backend and then log back in
12. Rerun Magento's compilation process before turning it back on (if you are using it)
A screencast is available to provide further guidance:
http://url.fooman.co.nz/youtubeinstall
Note: The thrill-seeker guide is is only recommended for experienced Magento users.
Updates and Feedback
This guide is continuously evolving to keep up with best practices for Magento and feedback I have received. To download the latest version, please go to
http://store.fooman.co.nz/ultimate-magento-extension-guide
Please don't hesitate to send me your feedback or ask me questions at
The Steps
1. Turn off Magento's Compilation Mode (if you have previously enabled it)
The compilation mode creates a copy of most files in your store for faster execution. However, it is vital to turn this off before installing anything new or making any code changes.
2. Verify your site is working correctly
Before installing anything new, it is good practice to verify that your current site works as expected. To ensure your site is running up to date code, refresh your Magento cache. This will highlight any unresolved issues associated with your existing site which will need to be resolved prior to installing any new
extension.
3. Backup your Magento files
Creating a backup will allow you to revert back to a previous version if you need to do so. If this is your first database backup, it is a good idea to take additional care in verifying that the back up is both complete and functional.
4. Turn on Magento maintenance mode
The reason for taking your store offline is that we will be taking a database backup in the next step. If we keep the store online and need to rollback to this backup, we would lose any orders that were placed after the backup was taken. The alternative to this approach would be to keep the store live but to re-add those orders manually in case you reverted to the old database.
From Magento version 1.4.0.0 onwards you can place your store into
maintenance mode by creating an empty file called “maintenance.flag” in the same folder as your main index.php file. Visitors to the site will be greeted by a “service temporarily unavailable” notice.
Unfortunately the maintenance flag also makes the site (including the backend) unavailable to you. So, I prefer to redirect everyone except myself to a static page saying that the site is currently unavailable but will be back online shortly.
One way to do this it to create a simple html file called
Adjust the IP address to your own and input the correct domain. This will redirect everyone except yourself (using the specified IP address) to the index_m.html file. You can include a logo image file in your static html file (logo.png).To prevent a loop, we don't redirect from index_m.html.
5. Create a database backup
The easiest option for creating a database backup is to use Magento's inbuilt tool. Go to System > Tools > Backups and hit “Create Backup”.
Depending on your database size and server speed, this may take a while. Once the backup is finished you can find the zipped backup under var/backups.
Alternatively, you can also use other programmes such as mysqldump (via the command line) or phpmyadmin to take a backup of your database.
Note: If you are using phpmyadmin, be sure to tick the “Disable Foreign Key Constraints” box to be able to properly restore the backup.
If this is your first backup, it is always a good idea to verify that your backup is working correctly on a separate database (regardless of which option you choose to run the backup).
6. Turn on Magento's cache
Turning on the configuration cache will prevent Magento from trying to install your new extension too early. If the extension has database changes to make, triggering the install too early could miss some instructions and create errors which are difficult to fix later on.
7. Install the extension
Always read the installation instructions that came with the extension! Although you may have read many installation instructions before, it is
important not to skip this vital step. Often, specific instructions or caveats are given for particular extensions, which are important to be familiar with for a successful extension installation.
With Magento there are a few different options to install a new extension: 1. Upload the files via FTP or SFTP (the option I recommend)
2. Use Magento's inbuilt Magento Connect Manager (easiest option, but comes with several pitfalls which are outlined below)
3. Use the command line and Magento Connect via pear
While I like the concept of the Magento Connect, I generally advise against using it. My main gripes with it are:
• Using Magento Connect can introduce a disparity between different extension versions on your test sit and live site
Because uploading the files via FTP or SFTP generally avoids most of the pitfalls outlined above, this is the option I recommend using.
If you are installing a commercial extension, you will most often be able to download the files as a zip file. For extensions only available on Magento
Connect, please see this post on Ashley's site for some great recommendations to get access to the files:
• http://www.aschroder.com/2011/01/downloading-a-magento-connect-extension-manually-before-installing-it/
• http://freegento.com/ddl-magento-extension.php (Use with a Magento Connect 1.0 key and download the ready2paste file)
• https://gist.github.com/776213 if you have command line access to a store
Assuming you have decided to install the extension by uploading the files via FTP or SFTP, you then need to upload the files to your Magento server once you have the files on your own computer. I use the free FTP tool Filezilla:
Once you are connected to your site, you can upload files by dragging the files from your local computer to your site.
Check the file permissions of the newly uploaded files - they need to be readable by the webserver. Pay particular attention to the user and group of the files, and to the file's read/write permissions. Ask your webhost or server administrator for details of the best settings to use. Alternatively you can compare file permissions against existing files on the server.
8. Refresh the Magento cache (or turn the cache off)
By refreshing the Magento cache, Magento will now register the addition of the new extension and will run any necessary installation routines.
9. Log out of your backend and then log back in
This step will reload any access rules for the backend and will prevent a
potential “Access Denied” error on newly added sections that you haven't been granted access to. Logging back in with a full administrator account will grant you these new permissions.
10. Verify that your site and new extension are working correctly
Check that your newly installed extension works as advertised. Check that the rest of your store still behaves as you would expect.
11. Turn off Magento maintenance mode
Bring the site back online by deleting the “maintenance.flag” file or the code you have added to the .htaccess file.
12. Rerun Magento's compilation process before turning it back on If you are using the compilation
mode, you need to hit the “Run Compilation Process” button.
Troubleshooting
I can't find the extension after installing it
If the newly installed extension is not listed under System > Configuration > Advanced > Disable Modules Output, try the following:
• Ensure the uploaded files' permissions can be read by Magento
• Flush Magento's cache and/or manually delete the contents of var/cache. In rare cases if var/cache is not writable by Magento, it will cache files in your system's tmp/ folder
This problem emerges when Magento can't read the file
app/etc/modules/NAME.xml (where NAME should relate to the module you just installed or the developer who created the module).
New configuration options do not appear after refreshing the cache
If new configuration options do not appear in the backend of your store after refreshing the cache several times, try the following:
• Ensure the uploaded files' permissions can be read by Magento
• Flush Magento's cache and/or manually delete the contents of var/cache. In rare cases if var/cache is not writable by Magento, it will cache files in your system's tmp/ folder
Potential conflicts between extensions
Due to Magento's architecture you can only replace each of the core classes of Magento once with an extension. Therefore, when installing more than one extension, you create a potential conflict. The potential for conflict is higher when two or more extensions replace similar Magento behaviour functions - only one extension can prevail. The potential conflict is unknown and depends on the combination of extensions used. Some further background information on this topic can be found in this article:
http://magebase.com/magento-tutorials/magento-extension-clashes-winners-and-loosers/
You can run a quick check for potential conflicts by downloading this file from the firegento project:
https://raw.github.com/firegento/firegento/master/src/firegento.php
Save the file as firegento.php and upload it via FTP to your Magento server. Opening the file in your browser http://www.example.com/firegento.php will advise you about potential conflicts based on extensions you have installed.
Links
[1] http://url.fooman.co.nz/youtubeinstall [2] http://store.fooman.co.nz/ultimate-magento-extension-guide [3] http://www.aschroder.com/2011/01/downloading-a-magento-connect-extension-manually-before-installing-it/ [4] http://filezilla-project.org/ [5] http://magebase.com/magento-tutorials/magento-extension-clashes-winners-and-loosers/ [6] https://github.com/firegento/firegentoFinal Words
Can this guide be improved? Is something not explained well enough? Do you have troubleshooting suggestions? Please let me know at [email protected]
