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 in a Lua 5.0 environment.

Windows users can use the pre-compiled version of Xavante's binary components (LuaSocket, LuaFileSystem and Rings) 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.

The $LUA directory should be part of the defined Lua Path (LUA_PATH in Lua 5.0, package.path in Lua 5.1) and the $LIB directory should be part of the defined Lua CPath (LUA_CPATH in Lua 5.0, package.cpath in Lua 5.1). Those directories can be even under the same upper directory if this is convenient, as the following Windows example show.

The Xavante source includes a file called t_xavante_start.lua, a template for the Xavante startup file (xavante_start.lua). The xavante_start.lua file is responsible for making sure the Lua Paths and CPaths are defined, setting the location of the XAVANTE_WEB global (corresponding to the $WEB directory) and starting the server itself.

The Xavante distribution assumes the Kepler file structure by default. If you want to use a diferent directory structure you'll have to edit the xavante_start.lua accordingly.

Note that the Kepler installation creates a separate directory for configuration files ($CONF) and adjusts the Lua Path accordingly to make sure that the files present on $CONF are found first. That allows the upgrade of Xavante and other components without overwriting the user configuration.

The examples below show the startup file xavante_start.lua for a Kepler installation in both Windows and Unix using the optional environment variable KEPLER_INIT. For more information on the use of KEPLER_INIT please check the Kepler documentation.

The Xavante startup file executes the kepler_init.lua configuration file to define the Lua Path and CPath and the system libray extension name (dll or so for example).

Windows Installation Example

If you are using Lua 5.0, an example of a Windows LuaBinaries 5.0.2 Release 2 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.

In the Kepler installation for Windows, the whole plataform is located in a common directory, called $HOME. This directory also contains the Lua executable, the Lua library and the Xavante startup file.

The Kepler Windows installer copies every need file to the Kepler $HOME directory but, if you are installing manually, for each of the projects downloaded from LuaForge, you'll have to copy the files to the corresponding directory below.

$HOME
    lua50.dll             -- LuaBinaries
    lua50.exe             -- LuaBinaries
    xavante_start.lua     -- Xavante (derived from t_xavante_start.lua)
    
     $CONF
        /cgilua
          config.lua      -- Copied from CGILua if non existant
        /xavante
          config.lua      -- Copied from Xavante if non existant
 
    $LIB
        lfs.dll           -- LuaFileSystem
        rings.dll         -- Rings
        /mime
            core.dll      -- LuaSocket
        /socket
            core.dll      -- LuaSocket
    
    $LUA
        compat-5.1.lua    -- Compat
        ltn12.lua         -- LuaSocket
        mime.lua          -- LuaSocket
        stable.lua        -- Rings
        /cgilua           -- CGILua
            ...        
        /copas            -- Copas
            copas.lua
        /coxpcall         -- Xavante
            coxpcall.lua
        /sajax            -- Xavante
            sajax.lua
        /socket           -- LuaSocket
            ...
        /xavante          -- Xavante
            ...
    
    $WEB
        index.lp          -- Xavante
        test.lp           -- Xavante
        /doc              -- Xavante (from /doc/us)
            ...
        /img              -- Xavante
            ...

Assuming a Windows installation where $HOME is located in c:\Kepler\1.0, the xavante_start.lua would be something like:

-- Kepler bootstrap
local bootstrap, err = loadfile(os.getenv("KEPLER_INIT") or
                                [[c:\kepler\kepler_init.lua]])
if bootstrap then
  bootstrap()
else
  io.stderr:write(tostring(err))
  return nil
end

XAVANTE_WEB = [[c:\Kepler\1.0\web]]
require "xavante"
xavante.start()

For that installation the kepler_init.lua file would be something like:

...
-- Lua 5.0 paths 
local conf50    = [[c:\kepler\1.0\conf]] -- $CONF
local luabase50 = [[c:\kepler\1.0\lua]]  -- $LUA
local libbase50 = [[c:\kepler\1.0\lib]]  -- $LIB
...

Unix Installation Example

An example of a Unix Xavante installation for Lua 5.0 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.

Note that, if you are installing manually, for each of the projects downloaded from LuaForge, you'll have to compile and copy the files to the corresponding directory as shown below:

$LIB  -- /usr/local/lib/lua/5.0 by default
	lfs.so            -- LuaFileSystem
	rings.so          -- Rings
	/mime
	    core.so       -- LuaSocket
	/socket
	    core.so       -- LuaSocket

$LUA  -- /usr/local/share/lua/5.0 by default
	compat-5.1.lua    -- Compat
	ltn12.lua         -- LuaSocket
	mime.lua          -- LuaSocket
	stable.lua        -- Rings
	/cgilua           -- CGILua
	    ...        
	/copas            -- Copas
	    copas.lua
	/coxpcall         -- Xavante
	    coxpcall.lua
	/sajax            -- Xavante
	    sajax.lua
	/socket           -- LuaSocket
	    ...
	/xavante          -- Xavante
	    ...

The Kepler Unix installer compiles and copies every needed file to the $LIB, $LUA directories. To make the Unix and Windows structures more similar, it creates the $HOME, $CONF and $WEB directories. The installer also creates symbolic links for $LIB and $LUA:

$HOME -- /usr/local/kepler/1.0 by default
	$CONF
        /cgilua
          config.lua      -- Copied from CGILua if non existant
        /xavante
          config.lua      -- Copied from Xavante if non existant
	
	/lib -- link to $LIB

	/lua -- link to $LUA

    $WEB
        index.lp          -- Xavante
        test.lp           -- Xavante
        /doc              -- Xavante (from /doc/us)
            ...
        /img              -- Xavante
            ...

The Kepler installer also assumes that the Lua executable and xavante_start.lua are located in the system path (usually at /usr/local/bin), here refered as $BIN:

$BIN
	lua50			-- from LuaBinaries
	xavante_start	-- from Xavante

It is also assumed that the Lua library can be found in the system path (usually at /usr/local/lib), here refered as $BINLIB:

$BINLIB
	liblua50.so		-- from LuaBinaries

The Xavante Makefile uses sed to build a xavante_start.lua that conforms to the above Kepler installation directories. An example of a generated xavante_start.lua would be:

#!/usr/bin/env lua50
-- Kepler bootstrap
local bootstrap, err = loadfile(os.getenv("KEPLER_INIT") or
                                [[/usr/local/kepler/kepler_init.lua]])
if bootstrap then
  bootstrap()
else
  io.stderr:write(tostring(err))
  return nil
end

XAVANTE_WEB = [[/usr/local/kepler/1.0/web]]
require "xavante"
xavante.start()

The kepler_init.lua file in Unix would be something like:

...
-- Lua 5.0 paths 
local conf50    = [[/usr/local/kepler/1.0/conf]]
local luabase50 = [[/usr/local/share/lua/5.0]]
local libbase50 = [[/usr/local/lib/lua/5.0]]
...

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

make
make install

Note that make install may require administrative privileges.

An example of a config file for Unix would be:

# System's libraries directory (where binary libraries are installed)
LUA_LIBDIR= /usr/local/lib/lua/5.0

# System's lua directory (where Lua libraries are installed)
LUA_DIR= /usr/local/share/lua/5.0

# System's executables directory (where binary or script executables are installed)
SYS_BINDIR= /usr/local/bin

# Complete path to Lua command line interpreter
LUA_INTERPRETER= /usr/local/bin/lua50

# Xavante default directory for HTTP documents
XAVANTE_HOME= /usr/local/kepler/1.0

# Kepler initialization file
KEPLER_INIT= /usr/local/kepler/kepler_init.lua

# Other Xavante directories are derived from XAVANTE_HOME
XAVANTE_LUA = $(XAVANTE_HOME)/lua
XAVANTE_CONF = $(XAVANTE_HOME)/conf
XAVANTE_WEB = $(XAVANTE_HOME)/web

Note that this config is not related to the $LUA/xavante/config.lua. The first is the configuration for the Unix installation, the latter is the configuration file for Xavante and is detailed in the next section.

Configuring

The file $LUA/xavante/config.lua defines the Xavante configuration in the Kepler installation, this file is copied to the $CONF/xavante directory to make it easier to upgrade a Xavante installation. The searching order of Lua Path will make the command require"xavante.config" find the file $CONF/xavante/config.lua before the file $LUA/xavante/config.lua, so upgrading Xavante with a newer version will not impact the current user configuration.

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"

-- Define here where Xavante HTTP documents are located
local webDir = XAVANTE_WEB

local simplerules = {
    { -- URI remapping example
    match = "/",
    with = xavante.redirecthandler,
    params = {"index.lp"}
    }, 

    
    { -- filehandler example
    match = "/*",
    with = xavante.filehandler,
    params = {baseDir = webDir}
    },
     
    { -- cgiluahandler example
    match = {"/*.lp", "/*.lua"},
    with = xavante.cgiluahandler.makeHandler (webDir)
    },
}

-- Displays a message in the console with the used ports
xavante.start_message(function (ports)
    local date = os.date("[%Y-%m-%d %H:%M:%S]")
    print(string.format("%s Xavante started on port(s) %s",
      date, table.concat(ports, ", ")))
  end)

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

Note the use of webDir both to set the base directory for the file handler and for the CGILua scripts. These paths should contain the desired directories if you are not using the Kepler structure.

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 xavante.bat file in Windows, or by giving execution rights to the xavante_start.lua on Unix.

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

@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 to a simple set of tests.

As a final note, if you start Xavante like this example showed, you will have to kill the process to stop Xavante since there is no "xavante_stop.lua". Kepler allows greater Xavante control in Windows by using a Xavante tray bar application that offers options to start and stop Xavante at will. For more detail consult the Kepler documentation.

Valid XHTML 1.0!

$Id: manual.html,v 1.41 2006/08/24 02:10:33 carregal Exp $