Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
|
litespeed_wiki:cache:litemage2:installation [2017/02/02 20:25] Jackson Zhang [Update LiteMage to a new version] |
litespeed_wiki:cache:litemage2:installation [2020/04/06 16:00] Jackson Zhang |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ===== LiteMage for Magento 2 Installation Guide ===== | ===== LiteMage for Magento 2 Installation Guide ===== | ||
| + | ==== Overview ==== | ||
| + | LiteMage setup is easy for both dedicated and shared hosting environments. Here are the basic steps. | ||
| - | ==== Prerequisites ==== | + | At the server level, you will need to: |
| + | - Get a LiteSpeed Enterprise 5.0+ License with the LiteMage Module (For more information on the available LiteMage tiers, visit **[[litespeed_wiki:cache:litemage:understand_tiers|Difference Between LiteMage Tiers]]**) | ||
| + | * **[[https://www.litespeedtech.com/products/litespeed-web-server/download/get-a-trial-license|Request Trial]]** | ||
| + | * **[[https://store.litespeedtech.com/store/cart.php|Purchase New]]** | ||
| + | * **[[litespeed_wiki:licenses:add-lscache|Upgrade existing]]** | ||
| + | - **[[litespeed_wiki:cache:common_installation#web_server_configuration|Configure your server level and virtual host level Cache Storage Path settings]]** | ||
| - | LiteSpeed Web Server Enterprise Edition with Magento 2 should be set up and working already. | + | For each Magento 2 Store, you will need to: |
| - | === PHP === | + | - Install the LiteMage extension for Magento 2 |
| + | - Turn on LiteMage through .htaccess | ||
| + | - Change the LiteMage extension's configuration to enable LiteMage | ||
| - | Magento 2 requires PHP versions 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 the server. If the version number does not match the one used within the server, there may be some compatibility issues. | + | ==== 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_wiki:cache:common_installation#web_server_configuration|LiteSpeed Cache Installation Guide]]** and follow the instructions in the **Set Server Level Cache Root** section of your respective guide. | ||
| - | Run the command ''which php'' to get the directory of the php binary. Then, change the current binary name to something different as a backup (e.g. ''mv php php-orig''). Lastly, symbolic link or copy the binary installed in the LSWS directory to the directory returned by the ''which'' command. If the ''which'' command doesn't return anything, we recommend using ''/usr/local/bin/'' or ''/usr/bin/''. | + | ==== PHP Prerequisites ==== |
| - | Example using PHP 7 with which returning /usr/bin/php: | + | LiteSpeed Enterprise with a working Magento 2 installation. Magento 2 works only with PHP 7 and hence requires PHP version 7.0.2+. |
| + | |||
| + | === On Control panel === | ||
| + | On control panel, you just need to select to the right PHP version. | ||
| + | |||
| + | === LSWS Native Mode=== | ||
| + | On LSWS native mode, you can run the following to check your PHP version. | ||
| + | |||
| + | 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 | mv /usr/bin/php /usr/bin/php-orig | ||
| ln -s /usr/local/lsws/lsphp70/bin/php /usr/bin/php | ln -s /usr/local/lsws/lsphp70/bin/php /usr/bin/php | ||
| - | Run ''php -v'' afterwards. If the steps were done correctly, the version number should match the server's php version. | + | If the steps were done correctly, running the ''php -v'' command should now return a version number matching the LiteSpeed's PHP version. |
| ==== Installation ==== | ==== Installation ==== | ||
| - | The following steps assume that the Prerequisites mentioned above are met. | + | The following steps assume that the Prerequisites mentioned above have been met. |
| - | - Access a terminal as the Magento directory owner (e.g. "user1") and cd to the Magento 2 root directory. If logged in as root, do ''su user1'' first. | + | - 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. |
| - | - If the current deploy mode is "default" instead of "production", you could install litemage2 without changing it to "production". If the current deploy mode is "production", you have to set the store to "developer" mode before installation and change it back to production after the installation.<code> | + | - 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:<code> |
| - | php bin/magento deploy:mode:set developer</code> | + | php bin/magento deploy:mode:set developer</code> |
| - | - There are two ways to get litemage2 packages: | + | - There are two ways to get the LiteMage 2 package: |
| - | * Method 1: Using composer to get latest litemage2 package<code> | + | * Method 1: Use composer to get latest LiteMage 2 package with command:<code> |
| - | composer require litespeed/module-litemage</code>or<code> | + | composer require litespeed/module-litemage</code> or for a specific version, command:<code>composer require litespeed/module-litemage:2.0.4</code> This will download the LiteMage 2 package from [[https://packagist.org/packages/litespeed/module-litemage|packagist.org]] and install it into directory ''vendor/litespeed''. It will need your username(public key) and password(private key) authentication for repo.magento.com. If you have not done so already, [[http://devdocs.magento.com/guides/v2.0/install-gde/prereq/connect-auth.html|Get your authentication keys]]. |
| - | composer require litespeed/module-litemage:2.0.4</code> It will get litemage2 latest package or specified version from https://packagist.org/packages/litespeed/module-litemage and install to vendor/litespeed. It will need your username(public key) and password(private key) authentication for repo.magento.com. Apply one if you don't have it. Please check here for details: http://devdocs.magento.com/guides/v2.0/install-gde/prereq/connect-auth.html | + | * Method 2: Download the LiteMage 2 package directly. |
| - | * Method 2: Download litemage2 package directly. | + | * [[https://github.com/litespeedtech/magento2-LiteSpeed_LiteMage/archive/master.zip|Download the package file from GitHub]]. |
| - | * Download the zip package file from this repository: https://github.com/litespeedtech/magento2-LiteSpeed_LiteMage/archive/master.zip. | + | * Unzip the source package with command: <code>unzip magento2-LiteSpeed_LiteMage-master.zip</code> |
| - | * Unzip the source package. The unzipped directory should be named magento2-LiteSpeed_LiteMage-master. | + | * In the Magento 2 root directory, create the needed directories with the following command: <code>mkdir -p app/code/Litespeed/Litemage</code> |
| - | * In the Magento 2 root directory, run the following command to create the needed directories<code>mkdir -p app/code/Litespeed/Litemage</code> | + | * Move the previously downloaded files into the newly created LiteMage directory with command: <code>mv /path/to/magento2-LiteSpeed_LiteMage-master/* app/code/Litespeed/Litemage/</code> |
| - | * Move the contents from the GitHub directory to the newly created directory:<code>mv /path/to/magento2-LiteSpeed_LiteMage-master/* app/code/Litespeed/Litemage/</code> | + | - Confirm that the owner of the files is consistent with the other Magento store files. |
| - | - Confirm that the contents' owner is consistent with the other magento store files. | + | - Enable LiteMage 2 in Magento with command: <code> |
| - | - Enable LiteMage 2 in magento:<code> | + | php bin/magento module:enable Litespeed_Litemage</code> |
| - | php bin/magento module:enable Litespeed_Litemage | + | - Upgrade Magento's setup with command:<code> |
| - | </code> | + | php bin/magento setup:upgrade</code> |
| - | - Upgrade the Magento setup:<code> | + | - Recompile using the signal-tenant/multi-tenant compiler. The single-tenant compiler has some [[http://devdocs.magento.com/guides/v2.0/config-guide/cli/config-cli-subcommands-compiler.html#config-cli-subcommands-single|known issues]] in earlier versions of Magento. If you are running Magento 2.0.6 or later **AND** have one Magento store, please run:<code> |
| - | php bin/magento setup:upgrade | + | php bin/magento setup:di:compile</code> If you are running Magento 2.0.5 or earlier **OR** have multiple Magento stores, Please run:<code> |
| - | </code> | + | |
| - | - Recompile using the signal tenant compiler or multi-tenant compiler. The single-tenant compiler has some issues. [[http://devdocs.magento.com/guides/v2.0/config-guide/cli/config-cli-subcommands-compiler.html#config-cli-subcommands-single|link]].If you have one website and store, please run:<code> | + | |
| - | php bin/magento setup:di:compile</code> If you have multiple websites and stores, Please run:<code> | + | |
| php bin/magento setup:di:compile-multi-tenant</code> | php bin/magento setup:di:compile-multi-tenant</code> | ||
| - | - If desired, switch back to production mode. The previous step may need to be repeated after the mode switch.<code> | + | - If desired, You may now switch your deploy mode back to "production" with the following command:<code> |
| - | php bin/magento deploy:mode:set production | + | php bin/magento deploy:mode:set production</code>**Note:** The previous step may need to be repeated after switching deploy modes. |
| - | </code> | + | |
| - | Note: For php 7.0.5 user, It may hit a bug which causing PHP Fatal error. The workaround is to delete var/di/relations.ser. It should not be problem with php 7.0.6 and above versions or non 7.x version.[[https://github.com/magento/magento2/issues/4070|link]]<code> | + | **Note:** PHP 7.0.x users running a version below 7.0.6 may run into a [[https://github.com/magento/magento2/issues/4070|PHP fatal error bug]]. A workaround for this is to delete file ''var/di/relations.ser'' with command:<code> |
| - | rm var/di/relations.ser | + | rm var/di/relations.ser</code> |
| - | </code> | + | |
| - | ==== Enable LiteMage after Installation: ==== | + | ==== Enable LiteMage After Installation: ==== |
| - | - In the Magento 2 root directory's .htaccess file, add the following lines:<code> | + | - Add the following lines to the top of your Magento 2 root directory .htaccess file:<code> |
| <IfModule LiteSpeed> | <IfModule LiteSpeed> | ||
| LiteMage on | LiteMage on | ||
| </IfModule> | </IfModule> | ||
| </code> | </code> | ||
| - | - Log into the Magento admin page. | + | - Log in to the Magento admin page. |
| - | - In Store -> Configuration -> Advanced -> System, make sure LiteMage is enabled and the Full Page Cache setting has LiteMage selected. | + | - In **Store > Configuration > Advanced > System**, make sure LiteMage is enabled and selected under the "Full Page Cache" setting. |
| - | - In System -> Cache Management, refresh configurations and page cache. | + | - 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. |
| - | - Visit and refresh a page that should be cache enabled. Look for the LiteMage related response headers. \\ Example:<code> | + | - 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.<code> |
| X-LiteSpeed-Cache: hit,litemage | X-LiteSpeed-Cache: hit,litemage | ||
| - | </code> | + | </code> 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_wiki:cache:litemage:installation#litespeed_web_server_settings|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 ==== | ||
| - | For related LiteSpeed Server setting configuration, please refer to: | + | 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) |
| - | [[https://www.litespeedtech.com/support/wiki/doku.php/litespeed_wiki:cache:litemage:installation#litespeed_web_server_settings|litespeed web server settings for litemage]] | + | |
| - | Tips: For dedicated VPS/server, although it's not "have to", to gain better performance with LiteMage, | + | **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: <code>Autoload error: 'Litespeed_Litemage' component already exist</code> |
| - | please make sure Check Public Cache setting in server cache policy part is set to Yes. | + | |
| - | ==== Update LiteMage to a new version ==== | + | ==== Testing ==== |
| + | You can use [[litespeed_wiki:cache:litemage:installation#testing|similar way as Litemage 1 testing]] to check the “X-LiteSpeed-Cache: hit,litemage” header. | ||
| - | You will pretty much follow the similar steps as installation. For downloading new package step, you can either remove the old package/downloadnew package through github or use compose to get new version through | ||
| - | <code>composer require litespeed/module-litemage:<version></code> Please keep consistent to use the same way as you initial installation otherwise it may generate duplicate copy and return "Autoload error: 'Litespeed_Litemage' component already exist". The rest of the steps will still need to be followed to ensure the update. | ||