How To: Enable and Use the LiteSpeed Plugin
===========================================

.. note:: 

   InterWorx does not support OpenLiteSpeed. 

InterWorx includes a plugin for LiteSpeed. This will replace Apache as the as the webserver. 

Because InterWorx does not handle PHP on servers using LiteSpeed, manual set up and management of PHP handlers and PHP versions for 
domains is required.

A paid license from LiteSpeed is required. LitesSpeed licenses can be purchased `here <https://www.litespeedtech.com/>`__. 

.. note::

   Domain-level error logging does not appear in the default location of ``/home/{unixuser}/var/{domain.com}/logs`` 
   on LiteSpeed servers. The LiteSpeed logs should be referenced, instead. These can be found at 
   ``/usr/local/lsws/logs/``.

.. contents:: 

Installing LiteSpeed
--------------------

Information on installing LiteSpeed can be found `on their website <https://docs.litespeedtech.com/lsws/installation/>`__.

#. When prompted in the LiteSpeed installation script, select option the option for InterWorx. In the following example, 
   that is option **6**:

   .. code-block::

      Will you use LiteSpeed Web Server with a hosting control panel?

      1. NONE
      2. cPanel
      3. DirectAdmin
      4. Plesk
      5. Hsphere
      6. Interworx
      7. Lxadmin
      8. ISPManager
      Please select (0-7) [0]? 6

#. When prompted in the LiteSpeed installation script, set the Port Offset to **0**:

   .. code-block::

      Would you like to run LiteSpeed along side with Apache on another port
      to make sure everything work properly? If yes, please set "Port Offset"
      to a non-zero value, LiteSpeed will run on Port 80 + "Port Offset",
      otherwise, set to "0" to replace Apache.

      Port Offset [2000]? 0

#. When the installation script is complete, check the status of the Apache service

   .. code-block::

      systemctl status httpd

#. If the Apache service is running, stop the service 

   .. code-block::

      systemctl stop httpd

#. Check the LiteSpeed service status

   .. code-block::

      systemctl status lsws

#. If LiteSpeed is stopped, start the service

   .. code-block::

      systemctl start lsws

#. If there are existing SiteWorx accounts on the server when LiteSpeed is enabled run the following to re-write the 
   vhosts to reflect the correct format for LiteSpeed. Newly created accounts will use the LiteSpeed format by default

   .. code-block::

      ~iworx/bin/httpd.pex --write-vhosts-all

To Enable the Litespeed Plugin
------------------------------

#. Log into NodeWorx, and navigate to **NodeWorx > Plugins** 
#. Click the **Pencil Icon** next to LiteSpeed Webserver, under the Miscellaneous heading. This opens the 
   Edit Plugin form 

   .. image:: /images/nw-litespeed-plugin.png
      :alt: litespeed plugin 

#. Select **Enabled** from the dropdown 

   .. image:: /images/nw-ls-edit-plugin.png
      :alt: edit plugin form 

#. Click **Save**

Managing PHP With LiteSpeed
---------------------------

Because InterWorx does not manage PHP on servers using LiteSpeed, users are required to manually install the ``lsphp`` versions, and set
up the handlers in the LiteSpeed admin interface.

.. warning:: 
   
   This means that management of **all** PHP options, extensions, etc, are **only** possible via LiteSpeed. InterWorx does not handle PHP on 
   LiteSpeed servers at all. 

   For example, if  PHP version of an domain is changed via SiteWorx, that change will not be applied. If PHP extensions are installed via the 
   PHP extensions page in InterWorx, they will not appear in the php versions available to the sites, etc.
   
   Any questions or issues that may arise with PHP on a LiteSpeed server must be directed to  `Litespeed's support <https://www.litespeedtech.com/support>`__.

Sites will use the highest version of PHP installed, by default. For example, if ``lsphp54``, ``lsphp71``, and ``lsphp80`` are all installed, 
all  of the domains will use  PHP 8.0 (``lsphp80``), unless there is an ``.htaccess`` file for the domain specifying otherwise. See `Changing a PHP Version for a Domain`_.

Adding the PHP Handlers
^^^^^^^^^^^^^^^^^^^^^^^

#. Log in to the server at the CLI as root, either via SSH or from the terminal
#. Run the following to install the LiteSpeed repo:

   For EL7 servers: 

   .. code-block::

      rpm -ivh https://rpms.litespeedtech.com/centos/litespeed-repo-1.3-1.el7.noarch.rpm

   For EL8 servers: 

   .. code-block::

      rpm -ivh https://rpms.litespeedtech.com/centos/litespeed-repo-1.3-1.el8.noarch.rpm

#. Install the desired ``lsphp`` versions. These are named ``lsphpXX`` with XX being the version of php. The 
   following example installs php 8.1:

   .. code-block::

      yum install lsphp81

#. Log into the LiteSpeed admin interface. This can be found at \https://{hostname.com}:7080 or \https://{ip.ad.re.ss}:7080, 
   replacing {hostname.com} or {ip.ad.re.ss} with the corresponding information

   .. note::

      If the LiteSpeed admin page cannot be accessed, please check the firewall settings on the server, as port 7080 
      may be blocked or unavailable. 

#. In the Litespeed admin interface, navigate to **Configuration > Server > PHP**
#. Under PHP Handlers, click **Add**. This opens the Add Handler form
   
   .. image:: /images/lsws-webadmin.png
      :alt: litespeed webadmin
 
#. Update the required fields: 

   - **Handler ID**: A name for the handler. The example in the following screenshot uses ``lsphp81``, since the handler will be set for PHP 8.1
   - **Command**: The path to the ``lsphp`` executable for the version. This is generally located at  ``/usr/local/lsws/lsphp{version}/bin/lsphp``,
     replacing ``{version}`` with ``lsphp`` version number
   - **Handled Suffixes**: The file extension/suffixes that should be processed by this handler, such as ``php``

   .. image:: /images/lsws-form.png
      :alt: litespeed add handler form 

#. CLick **Save**
#. Click **Graceful Restart** at the top of the page, to restart the Litespeed webserver 

   .. image:: /images/lsws-webadmin-updated.png
      :alt: litespeed webadmin with updated handler 
 
Changing a PHP Version for a Domain 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Log in to the server at the CLI as root, either via SSH or from the terminal
#. At the CLI, navigate to the docroot of the domain. This generally located at ``/home/{unixuser}/{domain.com}/html``, replacing ``{unixuser}``
   and ``{domain.com}`` with the corresponding information. The following example navigates to the docroot for the domain ``example.com``

   .. code-block::

      cd /home/exampleco/example.com/html

#. Using a text editor, create a file named ``.htaccess``, or open the exiting ``.htaccess`` file for editing. The following example uses the Vim 
   text editor. This command will both create a new file, and open an existing one to be edited

   .. code-block::

      vim .htaccess

#. Update the ``.htaccess`` file to include the following, replacing ``{handler ID}`` and ``{handled suffixes/file extensions}`` with the corresponding
   information:
 
   .. code-block::

      AddHandler application/x-httpd-{handler ID} .{handled suffixes/file extensions}

   The following example specifies the handler for ``lsphp74``, which is for PHP 7.4--please note the **(.)** before the file extension. That is 
   required:

   .. code-block::

      AddHandler application/x-httpd-lsphp74 .php

#. Save and exit the text editor
#. Update the permissions on the file. The correct permissions are ``{unixuser}:{unixuser}``, replacing ``{unixuser}`` with the 
   corresponding information

   .. code-block::

      chown {unixuser}:{unixuser} .htaccess

   Example:

   .. code-block::

      chown exampleco:exampleco .htaccess