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.