LiteMage for Magento 2 Installation Guide


LiteMage setup is easy for both dedicated and shared hosting environments. Here are the basic steps.

At the server level, you will need to:

  1. Get a LiteSpeed Enterprise 5.0+ License with the LiteMage Module (For more information on the available LiteMage tiers, visit Difference Between LiteMage Tiers)

For each Magento 2 Store, you will need to:

  1. Install the LiteMage extension for Magento 2
  2. Turn on LiteMage through .htaccess
  3. Change the LiteMage extension's configuration to enable LiteMage

Configure Server Level Cache Storage Settings

Server level cache storage needs to be configured properly for your environment. Select your server setup from the Web Server Configuration section of our LiteSpeed Cache Installation Guide and follow the instructions in the Set Server Level Cache Root section of your respective guide.


LiteSpeed Enterprise with a working Magento 2 installation.

Magento 2 requires PHP version 7.0.2+, 5.6.x, or 5.5.x. In the command line, type php -v to get the PHP version used by the command line interface. This version may be different than the one used by LiteSpeed. If the version number does not match the version used by LiteSpeed, you run the risk of compatibility issues.

In the command line, run command which php to get the location of the command line PHP binary, for example /usr/local/bin/php, and enter into that directory with command cd /usr/local/bin. If the which command doesn't return anything, we recommend using /usr/local/bin/ or /usr/bin/. Next, change the current PHP binary name to something different as a backup using the mv command and create a symbolic link to the LiteSpeed PHP binary (or copy the binary itself into the current directory).

For example, using PHP 7 with which php returning /usr/bin/php:

mv /usr/bin/php /usr/bin/php-orig
ln -s /usr/local/lsws/lsphp70/bin/php /usr/bin/php

If the steps were done correctly, running the php -v command should now return a version number matching the LiteSpeed's PHP version.


The following steps assume that the Prerequisites mentioned above have been met.

  1. Access a terminal as the Magento directory owner (e.g. “user1”) and cd into the Magento 2 root directory. If logged in as root, run the su user1 command first to become the Magento directory owner.
  2. If the current deploy mode is set to “default” instead of “production”, you can install LiteMage 2 without changing it to “production”. If the current deploy mode is set to “production”, you will have to set the deploy mode to “developer” before installation and change it back to “production” once installation is complete. You can do so with command:
    php bin/magento deploy:mode:set developer
  3. There are two ways to get the LiteMage 2 package:
    • Method 1: Use composer to get latest LiteMage 2 package with command:
      composer require litespeed/module-litemage

      or for a specific version, command:

      composer require litespeed/module-litemage:2.0.4

      This will download the LiteMage 2 package from and install it into directory vendor/litespeed. It will need your username(public key) and password(private key) authentication for If you have not done so already, Get your authentication keys.

    • Method 2: Download the LiteMage 2 package directly.
      • Unzip the source package with command:
      • In the Magento 2 root directory, create the needed directories with the following command:
        mkdir -p app/code/Litespeed/Litemage
      • Move the previously downloaded files into the newly created LiteMage directory with command:
        mv /path/to/magento2-LiteSpeed_LiteMage-master/* app/code/Litespeed/Litemage/
  4. Confirm that the owner of the files is consistent with the other Magento store files.
  5. Enable LiteMage 2 in Magento with command:
    php bin/magento module:enable Litespeed_Litemage
  6. Upgrade Magento's setup with command:
    php bin/magento setup:upgrade
  7. Recompile using the signal-tenant/multi-tenant compiler. The single-tenant compiler has some known issues in earlier versions of Magento. If you are running Magento 2.0.6 or later AND have one Magento store, please run:
    php bin/magento setup:di:compile

    If you are running Magento 2.0.5 or earlier OR have multiple Magento stores, Please run:

    php bin/magento setup:di:compile-multi-tenant
  8. If desired, You may now switch your deploy mode back to “production” with the following command:
    php bin/magento deploy:mode:set production

    Note: The previous step may need to be repeated after switching deploy modes.

Note: PHP 7.0.x users running a version below 7.0.6 may run into a PHP fatal error bug. A workaround for this is to delete file var/di/relations.ser with command:

rm var/di/relations.ser

Enable LiteMage After Installation:

  1. Add the following lines to the top of your Magento 2 root directory .htaccess file:
    <IfModule LiteSpeed>
    LiteMage on
  2. Log in to the Magento admin page.
  3. In Store > Configuration > Advanced > System, make sure LiteMage is enabled and selected under the “Full Page Cache” setting.
  4. In System > Cache Management, refresh the “Configuration” and “Page Cache” cache types. “Page Cache” should be enabled, if not, then LiteMage can not work and LiteMage Cache Management stats won't show up.
  5. To ensure that LiteMage is working correctly, visit a page that should be cache enabled and open your browser's inspector by right clicking the page and selecting “inspect”. Then select the “Network” tab and refresh the page. Now select the item from the list corresponding to your current HTML page (usually the first item ending in .html). Under “Headers”, check the response header for the following LiteMage related info.
    X-LiteSpeed-Cache: hit,litemage

    If you see X-LiteSpeed-Cache: miss,litemage, please refresh the page and check again.

For related server-level configurations, please refer to the LiteSpeed Web Server Settings section of our LiteMage (1) installation guide.

Tip: For dedicated/VPS servers, although not required, it is possible to improve LiteMage performance by setting “Check Public Cache” to “Yes” under Server > Cache > Cache Policy.

Updating LiteMage 2

The steps involved in updating LiteMage 2 to a newer version should be almost identical to the steps performed during installation. The only difference occurs when downloading a new package. At this point, if you installed LiteMage 2 using the GitHub method, you must remove the old package files and download the new package files through GitHub. (Composer update steps are identical to installation)

Important: Please be consistent when installing and upgrading LiteMage 2. Whether you installed LiteMage 2 using GitHub files or through Composer, always use the same method when updating to a newer version. If you do not do this you will generate a duplicate copy of LiteMage 2 and run into the following error:

Autoload error: 'Litespeed_Litemage' component already exist


You can use similar way as Litemage 1 testing to check the “X-LiteSpeed-Cache: hit,litemage” header.

litespeed_wiki/cache/litemage2/installation.txt · Last modified: 2018/03/16 21:19 by Jackson Zhang