README for LiteSpeed Lua module
===============================


Loading LuaJIT
==============

If the LuaJIT library (/usr/local/lib/libluajit*.so) is not currently installed,
you should download the current version from "luajit.org".

luajit.org/download.html
Current version: LuaJit 2.0.3 (2014-03-12)

Follow the installation instructions from this site.
Note that for LiteSpeed execution, the only necessary component of LuaJIT is
    libluajit.so

The default installation location of the LuaJIT library is
    /usr/local/lib/libluajit*.so

This is also the default where LiteSpeed looks for the shared library,
though it may be overwritten by specifying configuration parameters with WebAdmin.


Building the LiteSpeed Lua module
=================================

To build the LiteSpeed Lua module from source, an additional parameter
must be specified to LiteSpeed's "configure" program before "make"ing,
to indicate module compilation and where the LuaJIT header files exist.

If header files are in a standard directory:
    ./configure --with-lua=yes ...
    
Else to specify the directory (recommended):
    --with-lua=header_file_dir
    e.g., ./configure --with-lua=/home/user/LuaJIT-2.0.3/src ...
    
After making and installing, the module "mod_lua.so" is in LiteSpeed's
"modules" directory.

If one desires to simply remake the Lua module alone, without the top
level make and install, one may use the provided "Makefile.f" in the
Lua module source directory; however, this file may need to be edited
if an alternate header file directory is to be specified.
    make -f Makefile.f
 

Activating the LiteSpeed Lua module
===================================

(1) Using WebAdmin:
    (A) Add the module under the
        Configuration -> Server -> Modules tab
        (i) <Add>
            (a) Module -> enter "mod_lua"
            (b) <Save>
    (B) Enable the server to load Lua Scripts under the
        Configuration -> Server -> Script Handler tab
        (i) <Add>
            (a) Suffixes -> enter "lua"
            (b) Handler Type -> <Module Handler>
            (c) Handler Name -> <mod_lua>
            (d) <Save>
    (C) (optional) If the LuaJIT library is not in the default /usr/local/lib,
        specify the alternate directory with configuration parameters in the
        Configuration -> Server -> Modules tab
        (i) <Edit> the "mod_lua" entry
            (a) Module Parameters -> enter "lib"  library_path
                e.g., "lib  /mydirectory/mylibjit.so"
                      "lib  /home/user/LuaJIT-2.0.3/src/libluajit.so"
            (b) <Save>
    (D) Restart the server:
        Actions -> <Graceful Restart>
 
(2) Install/create a Lua Script in the "$VH_ROOT/html" directory.

    echo  'ls.say(ls.logtime(), "LiteSpeed: Hello", _VERSION)' \
      > $VH_ROOT/html/hello.lua

(3) Run the script from any browser:

    http://addr:port/hello.lua
    e.g., http://localhost:8088/hello.lua

    or execute

    curl -k -i http://localhost:8088/hello.lua

