# How to integrate LiteMage into Magento

> Learn how to install and enable LiteMage Cache for Magento 2 on Kualo hosting using Composer and the Magento CLI.

Source: https://www.kualo.com/knowledgebase/magento-performance/how-to-integrate-litemage-into-magento-v2
Updated: 2026-06-11

---

LiteMage Cache is a full-page cache extension for Magento 2, built on top of LSCache and designed specifically for Magento. It delivers both public and private block caching using ESI hole-punching for fast, complete page caching.

## Prerequisites

Before you begin:

- Your store should be running a supported PHP version for your Magento release (all current Magento 2.4 releases require PHP 8.x) with a memory limit of 2G, which Adobe recommends for command-line operations such as compilation.
- Composer requires the PHP ZIP extension.
- You should be comfortable working in a Unix shell over SSH, as Magento 2 uses Composer to manage packages.
- Disable any third-party full-page cache extension before proceeding. Do not disable Magento's built-in Page Cache type - LiteMage requires it to be enabled, and we confirm this in a later step.

You can adjust your PHP version, extensions, and memory limit using the [PHP Selector tool](/knowledgebase/cpanel-how-tos/how-to-manage-the-php-version-in-cpanel-using-the-select-php-version-tool).

![PHP Selector showing ZIP extension and memory limit settings](https://kb-cdn.kualo.com/d3/3c/d33c4c54165804f0092ee7a1cfe6aeb2f95c5a11.gif)

:::info
Contact our support team if you need help with any of the steps below.
:::

## Installing LiteMage 2

Log in to your account via SSH and change to your Magento 2 root directory. On a live store, enable maintenance mode first:

```bash
php bin/magento maintenance:enable
```

### Set the deploy mode

Check your current deploy mode:

```bash
php bin/magento deploy:mode:show
```

If it is set to "default" or "developer", you can install LiteMage without changing it. If it is set to "production", switch to developer mode for the installation:

```bash
php bin/magento deploy:mode:set developer
```

### Install via Composer

Run the following command to download and install LiteMage 2 from [packagist.org](https://packagist.org/packages/litespeed/module-litemage) into the `vendor/litespeed` directory:

```bash
composer require litespeed/module-litemage
```

If prompted to authenticate for repo.magento.com, enter your Magento authentication keys: the public key as the username and the private key as the password.

### Enable and configure the module

1. Enable the LiteMage 2 module in Magento:

```bash
php bin/magento module:enable Litespeed_Litemage
```

2. Run the Magento setup upgrade:

```bash
php bin/magento setup:upgrade
```

3. If you switched to developer mode earlier, switch back to production. This recompiles code and redeploys static content automatically, so no separate compile step is needed:

```bash
php bin/magento deploy:mode:set production
```

If your store runs in default mode and you did not switch, recompile manually instead:

```bash
php bin/magento setup:di:compile
```

4. Disable maintenance mode:

```bash
php bin/magento maintenance:disable
```

## Enable LiteMage after installation

1. Add the following block to the `.htaccess` file in your Magento root folder:

```apacheconf
<IfModule Litespeed>
  LiteMage on
</IfModule>
```

:::warning
If your `.htaccess` file is ever overwritten - for example by a deployment or an extension - this block must be re-added for LiteMage to keep working.
:::

2. Log in to the Magento admin panel and go to **Stores > Configuration > Advanced > System**.

3. In the "Full Page Cache" section, untick "Use system value" next to Caching Application, select **LiteMage Cache Built in to LiteSpeed Server**, and click **Save Config**.

4. Go to **System > Cache Management** and refresh the **Configuration** and **Page Cache** cache types. Confirm that Page Cache shows as enabled - LiteMage cannot work without it.

![Magento admin panel showing LiteMage selected as the full-page cache provider](https://kb-cdn.kualo.com/7c/5e/7c5eab1a987c79b4c97a2c2c3a4330e1170d3cf2.gif)

## Testing LiteMage

To confirm LiteMage is working:

1. Visit a page that should be cached.
2. Right-click the page and select **Inspect** to open your browser's developer tools.
3. Go to the **Network** tab and refresh the page.
4. Select the entry for the current HTML page (usually the first item in the list).
5. Under **Headers**, look for the following response header:

```
X-LiteSpeed-Cache: hit,litemage
```

If you see `X-LiteSpeed-Cache: miss,litemage`, refresh the page and check again - the first request populates the cache.

You can also test from the command line:

```bash
curl -sI https://www.yourstore.com/ | grep -i x-litespeed-cache
```

Run it twice; the first request may show a miss, the second should show a hit.

![Browser developer tools showing the X-LiteSpeed-Cache response header](https://kb-cdn.kualo.com/b9/96/b99628cb7177e96902d24d74068526193088e6c7.gif)

---

_Source: Kualo Knowledgebase — https://www.kualo.com/knowledgebase/magento-performance/how-to-integrate-litemage-into-magento-v2 · © Kualo Ltd._