The Ultimate Guide to Installing Magento Extensions

Transcription

1 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. Fooman 2012, Kristof Ringleff Page 1

2 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: 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 Please don't hesitate to send me your feedback or ask me questions at kristof@fooman.co.nz Last updated: Fooman 2012, Kristof Ringleff Page 2

3 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. Fooman 2012, Kristof Ringleff Page 3

4 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 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 index_m.html with your maintenance notice in your main Magento folder. Then add the following to the top of your.htaccess file: RewriteCond %{REMOTE_ADDR}!^192\.168\.0\.1$ RewriteCond %{REQUEST_URI}!/index_m.html$ RewriteCond %{REQUEST_URI}!/logo.png$ RewriteRule ^(.+) [L] Fooman 2012, Kristof Ringleff Page 4

5 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). Fooman 2012, Kristof Ringleff Page 5

6 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 Getting server file permissions right is complex, and too many people resort to giving read/write/execute permissions to everyone (777) in order to get the Magento Connect Downloader to work I like to inspect any code that I install first before running it. The Magento Connect Downloader downloads and installs in one step, without giving you a chance to do this Occasionally, installing an extension with Magento Connect Manager can trigger an upgrade of the Magento core itself, which you might not be prepared for. I believe this doesn't occur as often as it used to, but it is something to be aware of Fooman 2012, Kristof Ringleff Page 6

7 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: (Use with a Magento Connect 1.0 key and download the ready2paste file) 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. Fooman 2012, Kristof Ringleff Page 7

8 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. 13. Backup your Magento files and create another database backup (optional) Create a new file and database backup from your site in a known working state. This will save your work installing the new extension. 14. Repeat steps 1-13 for your live site Once you have successfully installed the new extension on your test site and are happy with its performance, repeat steps 1-13 to add the extension to your live site. Fooman 2012, Kristof Ringleff Page 8

9 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: You can run a quick check for potential conflicts by downloading this file from the firegento project: Save the file as firegento.php and upload it via FTP to your Magento server. Opening the file in your browser will advise you about potential conflicts based on extensions you have installed. Fooman 2012, Kristof Ringleff Page 9

10 Links [1] [2] [3] [4] [5] [6] Final Words Can this guide be improved? Is something not explained well enough? Do you have troubleshooting suggestions? Please let me know at Fooman 2012, Kristof Ringleff Page 10