LiteMage setup is easy for both dedicated and shared hosting environments. Here are the basic steps.
At the server level, you will need to:
- Get a LiteSpeed Enterprise 5.0+ License with the LiteMage module in one of the following ways:
- Configure your server-level and virtual-host-level Cache Storage Path settings:
For each Magento 2 Store, you will need to:
- Install the LiteMage extension for Magento 2
- Turn on LiteMage through .htaccess
- Change the LiteMage extension's configuration to enable LiteMage
LiteMage 2 requires LiteSpeed Enterprise with a working Magento 2 installation. Since Magento 2 works only with PHP 7, PHP version 7.0.2+ is required.
If you are using a control panel, simply choose the appropriate PHP version in the panel.
In LiteSpeed Web Server Native Mode, execute the following steps from the command line:
This command returns 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.
This command returns the location of the command line PHP binary, probably
/usr/local/bin/php. Enter the returned directory (if the
which command did't return anything, we recommend trying
/usr/bin/), like so:
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).
Using PHP 7 with
which php returning
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 LiteSpeed's PHP version.
Assuming that the Prerequisites mentioned above have been met, you are ready to begin installation.
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.
Set Deploy Mode¶
If the current deploy mode is set to
default, you can install LiteMage 2 without changing it. 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, like so:
php bin/magento deploy:mode:set developer
Get LiteMage Package¶
There are two ways to get the LiteMage 2 package: composer and direct download.
Use composer to get the latest LiteMage 2 package, like so:
composer require litespeed/module-litemage
To get a specific version, add the version number. For example:
composer require litespeed/module-litemage:2.0.4
This will download the LiteMage 2 package from packagist.org, and install it into the
You will need to provide your username(public key) and password(private key) authentication for
repo.magento.com. If you have not done so already, Get your authentication keys.
[[https://github.com/litespeedtech/magento2-LiteSpeed_LiteMage/archive/master.zip|Download the package file from GitHub]], and unzip the source package, like so:
In the Magento 2 root directory, create the required LiteMage directory with the following command:
mkdir -p app/code/Litespeed/Litemage
Move the previously downloaded files into the newly created LiteMage directory, like so:
mv /path/to/magento2-LiteSpeed_LiteMage-master/* app/code/Litespeed/Litemage/
Confirm File Ownership¶
Confirm that the owner of the files is consistent with the other Magento store files.
Enable LiteMage 2 in Magento with the following command:
php bin/magento module:enable Litespeed_Litemage
Upgrade Magento's Setup¶
Upgrade Magento's setup, like so:
php bin/magento setup:upgrade
Recompile using the single-tenant or 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 use the following command:
php bin/magento setup:di:compile
If you are running Magento 2.0.5 or earlier OR have multiple Magento stores, please use this command instead:
php bin/magento setup:di:compile-multi-tenant
Reset Deploy Mode¶
If desired, You may now switch your deploy mode back to
production with the following command:
php bin/magento deploy:mode:set production
The previous step may need to be repeated after switching deploy modes.
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 the
var/di/relations.ser file with the following command:
- Add the following lines to the top of your Magento 2 root directory .htaccess file:
<IfModule LiteSpeed> LiteMage on </IfModule>
- Log into the Magento admin page.
- In Store > Configuration > Advanced > System, make sure LiteMage is enabled and selected under the Full Page Cache setting.
- In System > Cache Management, refresh the Configuration and Page Cache cache types. Page Cache should be enabled. If it isn't, then LiteMage cannot work and LiteMage Cache Management statistics won't show up.
If your .htaccess file is ever overwritten you must re-add this code for LiteMage to work.
If LiteSpeed is running off of Apache configuration, then you need to verify that .htaccess files have been enabled.
Check your Apache configuration file for the related "Virtual Host" section and make sure the following is set:
<Directory /path/to/your/magento_store_installation> AllowOverride All </Directory>
LiteMage onin .htaccess.
For cPanel users, the auto-generated main configuration file in
/usr/local/apache/conf/httpd.conf may include other files like
/usr/local/apache/conf/userdata/std/2/test123/test123.com/*.conf. You need to check all included files to ensure that .htaccess is enabled.
Alternatively, the enable code can be placed in the virtual host conf section instead of in .htaccess.
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.
The steps involved in updating LiteMage 2 to a newer version in the future, 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)
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
We suggest testing LiteMage 2 in a pre-production environment. If you have to test on a live site, be sure to only enable LiteMage Cache for your admin IP address. This way, you can test caching on your own IP, while other IPs are served normally.
Visit your store. Use your browser's developer tool to check the response header for the store page's HTML file. This can usually be done by right clicking on the page and selecting some form of Inspect. Then click on the Network tab in the inspector and reload the page. Click the first listed HTML file.
If you see
X-LiteSpeed-Cache: hit,litemage in the response header, then the page is being served by LiteMage Cache. Unless someone else has visited the page before you, you should see
X-Litespeed-Cache:miss the first time the page is loaded. Then if you refresh the page, you will see
X-LiteSpeed-Cache: hit,litemage. If this is not the case, please see our troubleshooting guide.
You can set up cache warmup to warmup your litmage to ensure visitors' browsing served from cache instead of backend php and avoid "X-Litespeed-Cache:miss".