M-Turbo: Magento E-Commerce Accelerator Documentation

1. Introduction

M-Turbo is a new unique acceleration extension for Magento E-Commerce System, that aim to solve the Magento's weakest part - speed. The concept behind is based on the fact, that most of the pages - products, category lists or homepage are not changing often. Therefore, it is not needed to generate these pages every time. Run Magento Core to show individual page is slow operation. Most of these pages can be pre-cached - that is pregenerated - and then server has to just server page to visitors as pre-generated static HTML page. This approach significantly decreases time needed to generate and download the pages and saves significant amount of server resources for other actions.

M-Turbo does cache:

• first pages previews of selected categories (list of products in category)
• details of products of selected categories
• selected CMS sites
• homepage

• nothing, if the user is logged in
• second, third and other previews pages of categories
• search results
• information on the user accounts
• cart, cash box, currency box, checkout

Since version 1.2.0 it is possible to dynamically load the dynamic blocks. This functionality allows to cached pages with dynamic blocks as cart, comparison products, polls, etc. It is fully supported to have several websites, which are running from different directories.

Since version 1.2.1 it is possible to have several website, which are running from one directories.

2. Versions and Editions

M-Turbo is available in the two editions - free and paid version. Free version is available on Magento Connect or on M-Turbo product page.

You can buy paid version at our extensions e-shop.

3. The installation and uninstallation

The installation consists from the several simple steps and can be done in a three different ways - using the PEAR repository, using Magento Key Extensions or copy M-Turbo extension manually.

To upgrade from the older version to the new one we recommend to make uninstall the current version and then install the new version. How to uninstall M-Turbo correctly is described below.

Presumptions:
To continue following steps of installation, first make sure that:

• you have a running and functional Magento site
• permissions are set correctly to be able to install extensions

Installation Free Edition

You have three options how to install the free edition. You can use of the Magento connect service, Magento Extensions PEAR repository or do the installation manually.

PEAR-based installation from community channel

For installation from community channel let's visit extension page, you get installation key, which must be written into your Magento Connect Manager.

PEAR-based Installation from the local package

Go to the Magento eshop root. If you have not already used Magento Connect or any other Pear package management for your installation, you will need to run

./pear mage-setup

sudo chmod +x pear

./pear install /path/to/mturbo.tar.gz

Manuall Installation

To install M-Turbo manually, unzip the distribution package locally or on the remote server. Then merge the app directory of your Magento site installation with the app directory in the M-Turbo distribution package.

Before copy files to the server, make sure that you have the write permissions for the app directory.

Upgrading to Paid Edition of M-Turbo

You must enter your download id into field on the registration tab in admin panel of M-Turbo, to upgrade to the paid edition. After push button "Upgrade to full version" located at top left corner M-Turbo admin panel, diff files will be downloaded and free edition will be upgraded to the paid edition.

Standard cache must be refreshed after upgrade, if you have turned on Magento cache. The cache can be refreshed in the menu System > Cache Management.

If after insert the correct key and refresh Magento cache M-Turbo has not been upgraded to the paid edition, check the rights assigned to the directory app, which is in your Magento root. The web server must have permissions to write for directory app. Try upgrade again after adjustment the rights. If problem with upgrade persists, please contact us on support@artio.net

Direct installation the paid version

After purchase the paid version you receive the email containing a package of M-Turbo in the format of PEAR package or source code. The email contains also the license key (download id) that you may keep carefully. ou can make installation via local PEAR package or copy files manually (see guidelines of Installation Free Edition).

Uninstallation

In the version 1.2.0 is available an automatic uninstaller. You can find it in the admin panel of M-Turbo Uninstaller. If you open the control panel of uninstaller, the button Uninstall appears. M-Turbo will be completely removed from your Magento after pushing this button. Do not forget to refresh standard Magento Cache (System > Cache Management).

If you are running M-Turbo version 1.1.1 or later version and installed by Magento Connect, let's use this service to uninstall M-Turbo as well. We attention that uninstall process removes only files from the hard disk. The records in the database will remain.

If for any reason you can not use any of the above described methods of uninstallation, you can try to uninstall the M-Turbo manually.

Uninstall M-Turbo manually

1. Delete rewrite rules from the .htaccess file
   Open the file .htaccess in your favorite text editor (use only the clean text editors not Microsoft Word, OpenOffice Writer, etc.) The file .htaccesscan be found in the root directory of your particular 'website'. The rules written by M-Turbo are always beginning by the following sequence

   	############################################
   	## M-Turbo Acceleration (www.artio.net)
   		... The rules written by M-Turbo extension
   	## End M-Turbo
   					

   Delete M-Turbo rules to remove loading pages from the cache. Pages are generated directly using the Magento system if no M-Turbo rules in the .htaccess file.
2. Remove cached files
   Remove the directory that contains all cached files. Directory location depends on your choice in the first setting of M-Turbo. The default location is var/turbocache.
3. Remove source files from app directory
   Remove these source files and directories:
   • app/code/local/Artio/MTurbo
   • app/design/adminhtml/default/default/layout/mturbo.xml
   • app/design/adminhtml/default/default/template/mturbo
   • app/design/frontend/default/default/layout/mturbo.xml
   • app/etc/modules/Artio_MTurbo.xml
   • app/locale/en_US/Artio_MTurbo.csv
   • skin/frontend/default/default/js/mturbo.js
4. Delete records from the database
   Run the following command on your database

   	DROP TABLE `$PREFIXmturbo`;
   	DELETE FROM `$PREFIXcore_config_data` WHERE path LIKE '%mturbo%';
   	DELETE FROM `$PREFIXcore_resource` WHERE code LIKE 'mturbo_setup';
   					

   where $PREFIX replace by prefix of table name.
5. Reset standard Magento cache

4. The Recommended Process of Work with M-Turbo Extension

In this chapter you can find the recommended process of work with M-Turbo. This instruction manual may be used mainly for a primary understanding and orientation in the managing M-Turbo extension. For most of users should be this manual sufficient. More information about settings possibilities M-Turbo is available in the chapter Reference Manual, in which you should find all substantial information. If you have some problems or questions you can try to find the solution or answer in the chapter FAQ and Troubleshooting.

How does M-Turbo work?

If you want to use M-Turbo extension really effectively, it is good to have at least a rough idea about how it works. M-Turbo implementing so called "full page caching". This way of caching is characterized by the fact that source page is fully downloaded as file and than is offered to client as a normal static html file. There is no calling Magento Core so html pages are served significantly faster.

Full page caching system is suitable only for those pages, which are not changing very often. It is useful to cache in Magento lists of products, product details and static pages. The pages whose content is in the principle constantly changed (cart, cash box, user account, search results, etc.) are not possible to cache.

The parts of pages providing to user additional information can cause problem. The typical representative of those parts is block that informs to users about nubmer of products in the cart. Since version 1.2.0 is for these cases available a mechanism providing an additional server request to download these dynamic parts of page. Generally serving pages via M-Turbo is done in the two steps. Firstly server sends to the client cached page. Secondly dynamic blocks are loaded via AJAX. In the default setting these dynamic blocks are displayed: cart, products comparison, poll, number of products in the cart. Additionally you can add other dynamic blocks. Nevertheless adding of users block to the lists dynamically downloaded parts is not trivial matter and requires some experience of Magento design (especially layouts).

M-Turbo and caching system can not work properly if content is wrong coded. The next typical problem is a combination of a large number of categories and Java Script menu. In this case response time could be slow even using some caching system. The generating a menu with a large number of categories is also time consuming. In these cases we suggest to limit a depth of the generated menu.

Updating Pages

Cached pages must be updated sometimes. For example, when product price changed. There are two strategies of update. The first, when all pages are updated every day in the determined time. The second strategy is targeted update. The relevant page will be updated after any change in its content happend. For example, when is changed product price, category label, content CMS page etc. the page is updated automatically.

Targeted update strategy is enabled in the default settings. Step 8 below describes how to enable refresh cache automatically in the specific time.

How to set Magento for M-Turbo?

M-Turbo requires turend on server rewrites. Turn rewrites on could be done in the configuration of system Magento in the menu System > Configuration > Web > Search Engines Optimization > Use Web Server Rewrites.

For a right function of automatic download is necessary to have a correctly configured cron. You can read how to set cron, for example, on the page http://www.magentocommerce.com/wiki/how_to/how_to_setup_a_cron_job.

The relation M-Turbo extension to the standard Magento Cache

Standard Magento Cache affects the M-Turbo function in no way. Also M-Turo has no effect to the standard Magento cache. We recommend to turn on standard Magento Cache as well.

M-Turbo installation and setup

1. The Installation

   You can make installation according to one of the above instructions. If installation process proceeds successfully, you will be inform by following message:

   In the case when installation failed, the error message appears. Copy carefully this bug message and contact us at support@artio.net.

   If after installation no message appears, it is possible that the installation have not been finished properly. This situation can occur if you have already installed previously older M-Turbo version and that was not removed fully. Try to make an uninstallation according to the above mentioned instructions.

2. The initial configuration

   After instalaltion M-Turbo you can switch to the primary configuration. Using the main menu System > M-Turbo Management to open the M-Turbo admin panel. You see a following screen:

   

   The primary configuration consists in specification of licence key (Download Id), directory for saving cached pages and individual website setting. The directory for cached pages must have write permission. Do not choose a directory conflicting with some Magento system directory. Base Directory for each website we recommend to keep default. Change path only in the case when you are really sure that path is not location of your website.

   Screen of the free version differs. There is just one default website. Also text field for entering a license key is missing, because in the free downloadable version is not needed to use the license key.

   If you are not sure of any settings, do not worry, all data can be changed and restored everytime.

   After settings press the button Save and Install. M-turbo creates cache directory and adjust rewrite rules in .htaccess file. After installation and settings you see screen:

   

3. Htaccess rewrite rules, downloads

   After installation is appropriate to check if rewrite rules have been changed in the .htaccess file. Useful is also to check if download pages to the cache direcotory is working properly. Check download process is possible in the control panel Main Configuration.

   

   If you see on the position (2) green sign OK, it means, that the download of the test page have been successful. In the case of the red sign FAIL, try to change the download method using the drop-down menu (1). You have four options available. In the case when no method works, please contact us at support@artio.cz. You find a more detailed description of the options for download in the reference manual below.

   The check .htaccess rules is possible at the control panel Websites Configuration.

   

   The rewrite rules have been changed in .htaccess correctly, if position (B) has a sign yes and at position (C) a green sign Ready In case of problem or settings change, use button (D) to rebuild rewrite rules. If the button (D) is not in your administration, then is probably a problem with .htaccess file. Possible causes are: 1) file .htaccess file not found (Red sign Not found appears at the position (C)), 2) Web server has not write permission for .htaccess (Red sign Not writeable appears at the position (C)). The file .htaccess is searing always on path (A).

4. Selection pages to be cached

   After check page downloading and existence of rules in the htaccess file, you can proceed to select pages for caching. In the M-Turbo exists three types of cached pages (preview of categories, details of products, static CMS pages). Each of this page types have own control panel.

   

   Preview of categories refers to lists of products in this category. These lists are the most frequently visited pages. It is therefore appropriate to always cache these pages. Caching can be enabled / disabled for each category separately. Use checkbox, (D) in the control panel, for particular category to allow caching. If you wish to cache each new added categories automatically, set option (A) to Yes.

   

   Caching details of products is available only in the M-Turbo paid edition. Always consider very carefully which products have a sense to cache and which not. In the case of large number of products in the database, we do not recommend to cache all. Product selection is done via the categories. It is not possible to select individual products, but just category of products to be cached. In the case that the product belongs to the several categories, all alternatives are always cached automatically. The selection of categories is done as in the previous case, by check the appropriate category on the tree (D) in the control panel. If you wish to cache each new added product automatically in whatever category, set option (A) to Yes.

   

   CMS pages are the pages editable in admin panel CMS > Pages. Among the CMS pages is included also the homepage. In the free downloadable version is not possible to cache other CMS pages except the homepage. Each CMS page can have several variants according to the number of storeviews. The selection of cached pages is made via the control panel. After check a particular page (C), storeview will expand with the page variations. Here is possible to allow or deny caching. If you wish to cache each new added CMS page automatically, set option (A) to Yes. Page no-route is never included to the CMS pages list.

5. Synchronization - create list of cached pages

   It is important to make synchronization after selecting the cached pages. The synchronization creates a list of pages for caching. The list is created on the base of your choice. The synchronization starts by pressing the button Synchronization (B) in the list of pages.

   

   The synchronization is a relatively time-consuming process. Execution time depends on the number of pages to be cached. In the case of a large number of pages can synchronization takes tens of seconds.

6. Caching

   After synchronization, you can proceed to own caching. Caching is the process when the downloaded page are saved as HTML file on the server. The simplest way how to cache all pages is to check all items in the list and press the button Cache selected pages (A, in the previous pictures).

   Progress of caching - downloading pages to the cache file is possible to watch in the new opened window. This window will be closed automatically when process terminated. Time needed for caching depends on the number of cached pages and the server speed. It should be few minutes. In the case of very huge number of pages can be also tens of minutes.

   You can check the download page directly in the list of pages. For each item/page is shown the size and time of last download. Visual control cached page is performed by click to the link preview.

7. M-Turbo function verification

   It is possible to find time-stamp at the end of the page source code to check that page comes from the M-Turbo cache. Open the monitored page in your favorite browser. Press the right mouse button and select "View source code, or another similar offer. Go to the end of the page source code. If you see a timestamp the end (in the picture shown in green),

   

   then everything is set correctly and page have been served from the M-Turbo cache.

8. Automatic cache refresh settings

   The possibility of automatic download/cache is available only in the paid edition.

   Automatic download area performs refresh cache for all the currently permitted pages. It works on the principle of an external script (the script works only on Linux servers). In the simplest case, you should only allow automatic download and set the launch time. Updates will be performed every day at a certain time. Everything can be set in the main control panel configuration (2).

   

   The timestamp appears at the position (2) of the above picture, when last automatic updates terminated. If automatic cache refresh is not performing, please, go to the chapter Reference manual or FAQ and Troubleshooting, where you find more instructions what to do.

5. The Reference Manual

You can access M-Turbo administration by choosing System > M-Turbo Management in the Magento backend menu.

After opening the administration component of the M-Turbo you will see the main menu consisting of 10 items on the left. The meaning of individual menu items is described in the following table:

URL

This table contains a list of pages to be cached. All automatic caching is done based on this list. The list is prepared based on the URL rewrite list of the Magento core and list of CMS pages. In the case that list is not complete (new products has been just added) you can update the list by perform the synchronization action (B).

Any page in this list can be blocked and thus prevented to be cached. If you block already cached page, it will be automatically removed from the cache. Blocking and unblocking you can perform by actions Block/Unblock (E).

Each page is possible to download manually via link on the proper line (I), or check all lines together and click to the button Cache Selected Page (A). When batch caching is performed, new window si opened with the progress of page downloading (check followed image). This window do not close while downloading, otherwise the download is interrupted. Blocked pages are automatically skipped out.

Downloaded page can be viewed by pressing the link on the appropriate line (H). Pages is possible to remove from the cache one by one (G) or together via perform action Purge from disk (E). Page remains in the list after purge action. In the next download will be cached again. Perform action Delete (E) will remove page permanently.

The records in the table can be filtered by common way. The filter is applied by button Search (D), removed by button Reset Filter (C).

Columns description of the table

Main Configuration

This screen includes several options that control how the caching works as well as buttons to initiate cache-related actions. Any change should be saved by clicking the "Save Configuration" button located in the left-top corner of the page (position A in image).

The control panel of primary configuration contains of 5 sections:

M-Turbo path directory (1)

This section contains only field to change the main directory for cached files. If directory is changed, next step must be to rebuild htaccess rules (see Table Actions). Please, make sure that changed directory has rights for writing.

Automatic cache Management (2) (Only for paid version)

This panel is used for set up automatic cache refresh. External script is running and download all uncached pages. Scrip run just once a day. The exact time can be defined on this control panel. Furthermore, the control panel contains a label with information about the time the last scripts run. Whether the update is really done, you can also check by timestamp, located in the pages source.

The script is executed by directly calling, and it is important that the web server has rights to run it. On some servers can be this operation forbidden. In this case is important to enter absolute path to the interpret BASH, which is able to execute the script.

Choice download methods (3)

Section is used for select download methods. There are 4 options available:

• Using function file_get_contents. This function is not available on the most hosting servers.
• Download pages using sockets. The default settings available on the most hosting servers.
• Secure download using PHP CURL. This method is slightly slower than the previous two. It must be installed the PHP CURL extension on the server.
• Download using a new instance Magento. This is an extreme option for servers which have deny back requests to ourself. It is important to have installed Magento Patch. Patch can be installed using the button Apply Mage Patch in this section. After patch installation is possible to remove the patch using the same button. Label Remove Mage Patch on the button means that patch is installed.

Page download can be controlled using an on-line test routine built into the control panel. If any change download method, download of homepage is automatically proceeded. The result of this test is shown just below the combo box. In the case of a correct download is displayed green text OK added the size of the downloaded files. In the case of failure is displayed red text Fail with error message explaining the cause of the failure.

Filesize viewing (4)

This section is used to determine the minimum size of the page. Pages with smaller size are in the list of pages highlighted in red. Since version 1.2.1 are no such pages downloaded and cached. This setting prevents caching invalid or otherwise damaged pages.

Htaccess backup settings (5)

This section is used to set the backup .htaccess file after any change. If backup is enabled, a copy of htaccess file is created. Backups are found in the root directory under the names .htaccess.bak0, .htaccess.bak1, etc. The maximum number of created backups is set up in the field The maximum number of htaccess backup in this section. The oldest backup is automatically deleted when the number of backups is exceeded.

Website Configuration

The control panel contains settings related to the individual website. Each website has its own section and can be enabled or disabled (A). Pages, which belong to disabled website, are ignored. It is necessary to set in the (B) the absolute path to the website root for the particular website. This setting is necessary for a proper finding .htaccess file. (In version 1.2.0 is not allowed to have one path associated with the more websites, in version 1.2.1 is this restriction removed).

Area (C) contains control panel to enable or disable particular storeview, which belong to specific website. All pages, which belong to disabled storeview, are ignored.

In the area (D) are some information related to the website. Specifically there is the absolute path to the .htaccess file, information if .htaccess is editable and it is ready for re-build .htaccess rules by M-Turbo extension.

In the last area is pair of buttons. The first button (E) is used to the rebuild .htaccess rules. File .htaccess must be writable to rebuild rules. On the following picture you can see, how it looks, when .htaccess is not writable. The last button (F) is used to generate a list of URLs for caching. This list takes automatically external script to run caching. The user is informed about the number of registered URLs in the list, after the list established successfully.

Categories

This tab is used primary to select a category for caching. The categories are selected using the control (D). The choices (A,B,C) enable to add just created category to list of cached categories automatically. The option Add newly created categories to select means add just created category to list of selected categories for caching automatically. The option Enable automatic refresh for preview of saved category means download-cache just saved category automatically. Set option to Enable automatic refresh for previews of parents of saved category to yes, when you want to update pages of parent categories (for example parent category contains also list of child categories).

Products

This tab is used to select categories. The details of the all products falling to the selected categories will be cached. Each category is selected using the control (D). The choices (A,B,C) enable to add just created category to list of cached categories automatically. The option Add newly created categories to select means add just created category to list of selected categories for caching automatically. The option Enable automatic refresh for preview of categories of saved product means download-cache product detail and category preview, where product belons, automatically. When the product belongs to multiple categories it will be downloaded to all views, if these categories are selected. If you want to update also pages parent categories set to YES the option Enable automatic refresh for previews of parents of categories of saved product.

CMS

The tab CMS is used to select CMS pages for the caching. CMS sites are selected by the control panel (C), all language mutations will be offered after the click CMS (storeview) mutations of the site, if they exist. To automatically add pages to a selection is activated by set option Add newly created categories to select to YES. The option Enable automatic refresh after save CMS pages will activate automatic download CMS page after save.

Dynamicly Loaded Blocks

Using this control panel you can specify the blocks which will be loaded dynamically. Dynamic loading means that in the static html page will be instead of the block only JS script, which load block from your server. This approach allows showing dynamic data such as number of items in the cart, voting polls etc., on the fully cached pages as well.

The definition of dynamic blocks are divided into two parts. In the first part are the default blocks: The cart (a side block with a cart + update link on the cart in the header)(A), Poll (B), block of products comparison (C). These three blocks are firmly set up in the default Magento template. All will work correctly in the most Magento installation. Problem may occur if user's template are used. In this case it is necessary define the block manually. Write the names of blocks, in the text box (D), from your custom layout of your template.

In the case using Magenta 1.3.x, it is necessary to installation Layout Patch for a right function of dynamically downloadable blocks. Install this patch by press button Layout Patch, which is visible on this control panel. In the version 1.4.x and higher this patch is not needed and patch button is not visible.

Actions

There are five buttons for execute particular actions:

Registration

The following panel is used to register your license key. Enter key is required if you want to use the full paid version. The most of features are not available if key (Download id) is not entered properly. The license key you receive in the email, together with order information. Write license key into the box Your download id(A) and save configuration. If verification key proceed correctly, the screen message with your name and order date will be showen.

In the case of wrongly entered key you receive the following message.

The following message indicates that the license key is registered fine, but do not match the registered domain. Domain is filled in during the purchase process. If you are sure that domain is correct, please contact us via email support@artio.net. If you move M-Turbo to the other domain, you may do re-registration. More information are on our website Product registration.

Uninstallation

The button on this panel performs the removing component M-Turbo from your Magento.