Kepler
The Lua Web Development Platform

Unix/OS X Installation Instructions

This document shows how to install Kepler from sources on Unix-like systems such as Linux and Mac OS X. The procedures are almost the same on all Unix systems, differences will be explicitly noted below.

Requirements

At its core, Kepler depends only on Lua. You can get Lua from your distribution, from the LuaBinaries project, build Lua yourself from the sources available at lua.org, or let Kepler build it for you. Make sure you see the Finding Lua section below if you plan to use a pre-built Lua rather than letting Kepler build Lua.

If building Lua, you can enable command history facilities in its interactive interpreter by using the optional package GNU Readline; the build process will use it if available, or it can be disabled explicitly. On Linux, Readline depends also on NCurses.

Additionally, optional modules distributed with Kepler require some external libraries, which become build dependencies if they are selected during configuration. Requirements for optional modules are:

  • Expat, required by LuaExpat
  • ZZipLib, required by LuaZip
  • FCGI, required by the FastCGI launcher
  • For LuaSQL, one of the following, depending on the selected driver:

Development packages (libraries and headers) for these additional dependencies should be installed in the system. On Linux distributions, package repositories usually include development packages marked as -dev or -devel.

On Mac OS X, these additional dependencies can be fulfilled installing those packages manually or using repositories of additional software, such as Fink.

The build process

The build process uses the familiar "configure; make; make install" routine. However, you'll typically want to pass some options to the configure script in order to specify installation directories, which Kepler launcher to use and which optional modules to build.

Configuring

The command:

./configure --help

will list all available flags, as well as the default values for the particular version of Kepler you are building. The three fundamental flags are:

--prefix=DIR Directory where Kepler should be installed. All Kepler components will be installed relative to the given path.
--sysconfdir=DIR Directory where Kepler configuration files should be installed. All Kepler configuration files will be installed relative to the given path (ie, --sysconfdir=/etc will result in a directory called /etc/kepler/1.1/).
--includedir=DIR Directory where C header files should be installed. This is used when Kepler builds Lua.
--kepler-web=DIR Root of the directory tree of files to be served by the web server. When Xavante is compiled, it is configured to use this directory; other Kepler launchers could be configured to use it as well.
--kepler-log=DIR Directory for Kepler log files to be stored.
--launcher=LAUNCHER Which launcher to use. Valid options are:
  • cgi - to build a CGI launcher
  • fastcgi - to build a FastCGI launcher
  • mod2 - to build an Apache 2 module, mod_lua
  • xavante - to build Xavante, a native Lua webserver which offers a native Kepler launcher
--with-optional=PACKAGES A comma-separated list of optional packages to build. Valid options are:
  • lualogging - a simple API to use logging features in Lua
  • luasql - database connectivity for the Lua programming language
  • luaexpat - XML Expat parsing for the Lua programming language
  • luazip - allows reading files inside zip files
  • md5 - a basic cryptographic Library for Lua

Finding Lua

You may want to specify whether Lua should be compiled and installed along in the Kepler prefix, or if the build should use an already-existing installation of Lua from your system. By default, the configure script will try to detect the presence of Lua in your system, but you can specify this explictly using one of the following flags:

--enable-lua Build and install Lua along with Kepler.
--disable-lua Do not build or install Lua along with Kepler, use the one available in the system.
--with-lua=PREFIX Do not build Lua, use Lua from given prefix.
--with-lua-include=DIR When using a pre-built Lua, you can also specify its includes dir if configure fails to find it.
--with-lua-lib=DIR When using a pre-built Lua, you can also specify its libraries dir if configure fails to find it.
--lua-suffix=SUFFIX Versioning suffix to use in Lua filenames. For example, --with-lua-suffix=5.1 instructs Kepler to use names such as lua5.1 and liblua5.1.a; --with-lua-suffix= corresponds to names such as lua and liblua.a.
--with-readline=DIR Lua can be built with Readline support for command history facilities in its interactive interpreter. This flag can be used to supply its location in case it fails to be automatically found.
--without-readline To cut down the number of dependencies at expense of losing the command history facilities in the interpreter, Readline support can be disabled when building Lua along with Kepler.
--with-ncurses=DIR Prefix where NCurses is installed. Used by Lua when Readline is enabled on Linux.

External dependencies

The following flags can be used to specify options relative to optional components. Of special importance is the flag for specifying which SQL driver to use.

--with-luasql-driver=DRIVER When Which SQL driver to use with LuaSQL. Valid options are:
  • odbc - build the UnixODBC driver
  • postgres - build the PostgreSQL driver
  • oci8 - build the OCI8 driver
  • sqlite - build the SQLite 2.x driver
  • mysql - build the MySQL driver
--with-expat=DIR Prefix where Expat is installed. Used by LuaExpat.
--with-zzip=DIR Prefix where ZZip is installed. Used by LuaZip.
--with-oci8=DIR Prefix where OCI8 is installed. Used by the OCI8 driver for LuaSQL.
--with-mysql=DIR Prefix where MySQL is installed. Used by the MySQL driver for LuaSQL.
--with-postgres=DIR Prefix where Postgres is installed. Used by the PostgreSQL driver for LuaSQL.
--with-sqlite=DIR Prefix where SQLite is installed. Used by the SQLite driver for LuaSQL.
--with-odbc=DIR Prefix where UnixODBC is installed. Used by the ODBC driver for LuaSQL.
--with-fastcgi=DIR Prefix where FCGI is installed. Used by the FastCGI launcher.
--with-apache=DIR Prefix where Apache is installed. Used by the Mod2 launcher.

Build example

As an example, the following setup will configure Kepler to build LuaBinaries and the optional components LuaLogging, LuaSQL and MD5, and use MySQL as its LuaSQL driver (the following should be entered in a single line).

./configure --enable-lua --with-optional=lualogging,luasql,md5 --with-luasql-driver=mysql

The configure script will then output information such as this: (exact values may vary according to the system)

Will build Lua along with Kepler.
Will install Lua along with Kepler.
Checking for MySQL... found: /Programs/MySQL/4.1.12/include/mysql/mysql.h
Writing configuration...
Installation prefix: /usr/local
Launcher: xavante
Optional packages: lualogging,luasql,md5

Done. You can now run 'make' to build.

If any of the checks fail, you may need to pass additional flags specifying where required libraries are to be found (see the particular error messages for more information). If no errors were reported, you can proceed to the next step and build Kepler with:

make

Please note that as of Kepler 1.1, the Makefile assumes that make is GNU Make (which is true for Linux and Mac OS X systems; other BSD variants may need to temporarily replace make in their $PATH with a symlink to gmake).

Once the build is completed, you can install Kepler with:

make install

Depending on your selected installation directory, you may need to perform the above step with superuser privileges, using su or sudo -- for example, on an account with administrative privileges on Mac OS X, you can run:

sudo make install

Configuring the Web Server

Your Web server has to be configured to use Kepler and this configuration depends not only on the Web server being used, but also on the choosen launcher. After editing your Web server configuration you may need to restart it to activate the new configuration.

For more details on the Unix Web server configuration for Kepler please check:

  • Apache 2 - supports mod_lua, FastCGI and CGI launchers
  • Lighttpd - supports FastCGI and CGI launchers
  • Xavante - offers a native launcher

Valid XHTML 1.0!

$Id: install.unix.html,v 1.32 2007/11/21 19:34:06 carregal Exp $