Xavante
A Lua Web Server with CGILua support

Installing

Xavante follows the package model for Lua 5.1, therefore it should be "installed". Refer to Compat-5.1 configuration section about how to install the modules properly.

Windows users can use the pre-compiled version of Xavante's binary components (LuaFileSystem and LuaSocket) available at LuaForge.

Xavante installation is very flexible and is based on three directories:

$LIB - Lua binary libraries

$LUA - Lua libraries

$WEB - Xavante HTTP documents.

For convenience, those directories can be under the same home directory as the following examples show.

The Xavante source includes a file t_xavante_start.lua. This is a template for the Xavante startup file. You must edit it so it reflects your system paths and then rename it to xavante_start.lua.

Windows Installation Example

An example of a Windows LuaBinaries compatible Xavante installation is the one used by Kepler. It is shown below with the list of included files and where those files can be found in LuaForge.

For each of the projects downloaded from LuaForge, you'll have to copy the source files to the corresponding directory below. Note that sometimes the LuaForge download may include a somewhat different name for the directory.

$HOME
    lua50.dll             -- LuaBinaries
    lua50.exe             -- LuaBinaries
    xavante_start.lua     -- Xavante (t_xavante_start.lua)
    
    $LIB
        lfs.dll           -- LuaFileSystem
        lmime.dll         -- LuaSocket
        lsocket.dll       -- LuaSocket
    
    $LUA
        compat-5.1.lua    -- Compat
        ltn12.lua         -- LuaSocket
        mime.lua          -- LuaSocket
        stable.lua        -- VEnv
        venv.lua          -- VEnv
        /cgilua           -- CGILua
            ...        
        /copas            -- Copas
            ...
        /coxpcall         -- Xavante
            coxpcall.lua
        /sajax            -- Xavante
            sajax.lua
        /socket           -- LuaSocket
            ...
        /xavante          -- Xavante
            ...
    
    $CONF
        /cgilua
          config.lua      -- CGILua
        /xavante
          config.lua      -- Xavante
        
    $WEB
        index.lp          -- Xavante
        test.lp           -- Xavante
        /doc              -- Xavante (doc/us)
            ...
        /img              -- Xavante
            ...

Note that the Kepler installation creates a separate directory for configuration files ($CONF) and adjusts LUA_PATH accordingly to make sure that the files present on $CONF are found first.

The example below shows the startup file xavante_start.lua for a Kepler Windows installation on c:\kepler.

--- compatibility code for Lua version 5.0 providing 5.1 behavior
if string.find (_VERSION, "Lua 5.0") and not _COMPAT51 then
  if not LUA_PATH then
    LUA_PATH = "c:/kepler/conf/?.lua;"..
               "c:/kepler/lua/?.lua;"..
               "c:/kepler/lua/?/?.lua;"..
               "c:/kepler/lua/?/init.lua;"
  end
  require"compat-5.1"
  package.cpath = "c:/kepler/lib/?.dll"
end

require "xavante.server"

xavante.setwebdir("c:/kepler/web/")
xavante.start(XAVANTE_ISFINISHED, XAVANTE_TIMEOUT)

Linux Installation Example

And example of a Linux Xavante installation is the one used by Kepler. It puts the $HOME directory at /usr/local/kepler, the $LIB directory at /usr/local/lib/lua/5.0, with a symbolic link at $HOME/lib, the $LUA directory at /usr/local/share/lua/5.0, with a symbolic link at $HOME/lua. It also assumes that the Lua executable, the Lua Library and xavante_start.lua are located in the system path (usually /usr/local/bin).

The Linux Makefile uses sed to build a xavante_start.lua that conforms to the above Kepler installation directories.

The Linux Xavante installation would differ only in the contents of the $LIB directories

$HOME
    $LIB
        lfs.so
        lmime.so
        lsocket.so

and in the definition of the paths in xavante_start.lua:

--- compatibility code for Lua version 5.0 providing 5.1 behavior
if string.find (_VERSION, "Lua 5.0") and not _COMPAT51 then
  if not LUA_PATH then
    LUA_PATH = "/usr/local/kepler/conf/?.lua;"..
               "/usr/local/share/lua/5.0/?.lua;"..
               "/usr/local/share/lua/5.0/?/?.lua;"..
               "/usr/local/share/lua/5.0/?/init.lua;"
  end

  require"compat-5.1"
  package.cpath = "/usr/local/lib/lua/5.0/?.so"
end

require "xavante.server"

xavante.setwebdir("/usr/local/kepler/web/")
xavante.start(XAVANTE_ISFINISHED, XAVANTE_TIMEOUT)

To install Xavante from the distribution source in a Linux enviroment, simply edit the config file to use the correct paths for your system and do:

make
make install

Configuring

The file $LUA/xavante/config.lua defines the Xavante configuration. On the Kepler example, this file is copied to the $CONF/xavante directory to make it easier to upgrade a Xavante installation since the searching order of LUA_PATH will make the command require"xavante.config" find the $CONF/xavante/config.lua before the $LUA/xavante/config.lua.

Xavante defines virtualhosts for each site that it is running. Each virtualhost can define a set of rules for it. Each rule matches a URL pattern with a handler. Xavante currently offers a file handler, a redirect handler and a CGILua handler for general files, URL remapping and CGILua scripts respectively.

A typical config.lua uses the format below

require "xavante.filehandler"
require "xavante.cgiluahandler"
require "xavante.redirecthandler"

local simplerules = {
    -- URL remapping example
    {match = "/", with = xavante.redirecthandler,
    params = {"index.lp"}}, 
    -- filehandler example
    {match = "/*", with = xavante.filehandler,
    params = {baseDir = xavante.webdir()}},
    -- cgiluahandler example
    {match = {"/*.lp", "/*.lua"},
    with = xavante.cgiluahandler.makeHandler (xavante.webdir())},
}

xavante.HTTP{
    server = {host = "*", port = 80},
    
    defaultHost = {
    	rules = simplerules
    },
}

To use virtual hosts with Xavante, the call to xavante.HTTP would be changed to something like

xavante.HTTP{
    server = {host = "*", port = 80},
    
    defaultHost = {},
    
    virtualhosts = {
        ["www.sitename.com"] = simplerules
    }
}

Running

Running Xavante requires the execution of the correctly set xavante_start.lua. This can be done through a .bat file in Windows, or by giving execution rights to the xavante_start.lua on Linux.

The example below is a xavante.bat that can be used to start Xavante in Windows using the same configuration as the above examples.

@echo Xavante Started
@c:\kepler\lua50.exe c:\kepler\xavante_start.lua

Remember that xavante_start.lua is the configured version of t_xavante_start.lua and if you are installing Xavante from the source files you should edit it first.

After Xavante is started, opening the URL http://localhost on your browser should show the Xavante welcome page. If you changed the port number on config.lua you should also use this port number in the URL.

The welcome page presents the Xavante version and links to the documentation and for a simple set of tests.

Valid XHTML 1.0!

$Id: manual.html,v 1.29 2005/07/12 20:56:47 uid20002 Exp $