# Installation¶

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 in one of the following ways:
2. Configure your server-level and virtual-host-level Cache Storage Path settings:

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

## PHP Prerequisites¶

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:

php -v


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.

which php


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/local/bin/ or /usr/bin/), like so:

cd /usr/local/bin


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).

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 LiteSpeed's PHP version.

## Installation¶

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.

#### Composer¶

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 vendor/litespeed directory.

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:

unzip magento2-LiteSpeed_LiteMage-master.zip

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¶

Enable LiteMage 2 in Magento with the following command:

php bin/magento module:enable Litespeed_Litemage


php bin/magento setup:upgrade

### Recompile¶

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

Tip

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

Warning

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:

rm var/di/relations.ser

## Enable LiteMage¶

1. Add the following lines to the top of your Magento 2 root directory .htaccess file:<IfModule LiteSpeed> LiteMage on </IfModule>
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 it isn't, then LiteMage cannot work and LiteMage Cache Management statistics won't show up.

Warning

If your .htaccess file is ever overwritten you must re-add this code for LiteMage to work.

Warning

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>

If it is set to "AllowOverride None", .htaccess files will be disabled. Therefore, LiteMage will not be enabled even if you place LiteMage on in .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.

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.

## Update LiteMage¶

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)

Warning

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

## Test LiteMage¶

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".

Last update: July 15, 2020