NOTE: This is just one way to configure your server to run Orbit applications; it does require that you have root access. There are also local sandboxed methods which we will cover in a future article.

Installing Apache

Connect to your server. Use ssh or however your host instructs you, and install Apache2 and support modules:

$ sudo apt-get install apache2 libapache2-mod-fcgid libfcgi-dev build-essential

Enable required Apache2 modules:

 $ sudo a2enmod rewrite
 $ sudo a2enmod fcgid
 $ sudo /etc/init.d/apache2 force-reload

Install LuaRocks

If you are running a fresh distribution (Ubuntu Lucid or Debian Squeeze) then you can get a suitable LuaRocks from the repositories – otherwise you must install it directly, as described below. If unsure, look at ‘aptitude show luarocks’ – the luarocks version must be 2.0.x. This will also make sure you have Lua and its development library:

$ sudo apt-get install luarocks

Otherwise, you have to do it by hand:

Install Lua, using the appropriate methods for your system.

$ sudo apt-get install lua5.1 liblua5.1-0-dev

Download and unpack the LuaRocks tarball (http://luarocks.org/releases).

$ wget http://luarocks.org/releases/luarocks-2.0.2.tar.gz
$ tar xvfz luarocks-2.0.2.tar.gz

Change directories to the new extracted LuaRocks directory and configure. (This will attempt to detect your installation of Lua. If you get any error messages, the main problem will probably be the location of the Lua include files – this uses the standard Debian/Ubuntu locations.

$ cd luarocks-2.0.2
$ ./configure --with-lua-include=/usr/include/lua5.1"
$ make
$ make install

Install WSAPI, fcgi, Orbit, and Xavante

$ sudo luarocks install orbit
$ sudo luarocks install wsapi-xavante
$ sudo luarocks install wsapi-fcgi

[Optional] Install support libraries; LuaSQL,Sqlite3 and md5:

$ sudo apt-get install libmysqlclient15-dev libsqlite3-dev
$ sudo luarocks install md5
$ sudo luarocks install luasql-sqlite3
$ sudo luarocks install luasql-mysql MYSQL_INCDIR=/usr/include/mysql

Setting up Apache2

Edit the site config file with your favourite editor. (default site is named ‘default’)

$ sudo joe /etc/apache2/sites-available/default

Add this following section below the <Directory /var/www/> section of the config file. If this section has a ‘AllowOverride None’ then you need to change the ‘None’ to ‘All’ so that the .htaccess file can override the configuration locally.

<IfModule mod_fcgid.c>
    AddHandler fcgid-script .lua
    AddHandler fcgid-script .ws
    AddHandler fcgid-script .op
    FCGIWrapper "/usr/local/bin/wsapi.fcgi" .ws
    FCGIWrapper "/usr/local/bin/wsapi.fcgi" .lua
    FCGIWrapper "/usr/local/bin/op.fcgi" .op
    #FCGIServer "/usr/local/bin/wsapi.fcgi" -idle-timeout 60 -processes 1
    #IdleTimeout 60
    #ProcessLifeTime 60
</IfModule>

Restart the server.

To enable your application you need to add +ExecCGI to an .htaccess file in the root of your Orbit application – in this case, /var/www.

Options +ExecCGI
DirectoryIndex index.ws

Here is a simple example of a “Hello World” orbit application. Put this in /var/www/index.ws

    #!/usr/bin/env wsapi.fcgi
 
    require"orbit"
 
    -- Orbit applications are usually modules,
    -- orbit.new does the necessary initialization
 
    module( "hello", package.seeall, orbit.new )
 
    -- These are the controllers, each receives a web object
    -- that is the request/response, plus any extra captures from the
    -- dispatch pattern. The controller sets any extra headers and/or
    -- the status if it's not 200, then return the response. It's
    -- good form to delegate the generation of the response to a view
    -- function
 
    function index( web )
        return render_index()
    end
 
    function say( web, name )
        return render_say( web, name )
    end
 
    -- Builds the application's dispatch table, you can
    -- pass multiple patterns, and any captures get passed to
    -- the controller
 
    hello:dispatch_get( index, "/", "/index" )
    hello:dispatch_get( say, "/say/(%a+)" )
 
    -- These are the view functions referenced by the controllers.
    -- orbit.htmlify does through the functions in the table passed
    -- as the first argument and tries to match their name against
    -- the provided patterns (with an implicit ^ and $ surrounding
    -- the pattern. Each function that matches gets an environment
    -- where HTML functions are created on demand. They either take
    -- nil (empty tags), a string (text between opening and
    -- closing tags), or a table with attributes and a list
    -- of strings that will be the text. The indexing the
    -- functions adds a class attribute to the tag. Functions
    -- are cached.
    --
 
    -- This is a convenience function for the common parts of a page
 
    function render_layout( inner_html )
        return html
        {
            head{ title"Hello" },
            body{ inner_html }
        }
    end
 
    function render_hello()
        return p.hello "Hello World!"
    end
 
    function render_index()
        return render_layout( render_hello() )
    end
 
    function render_say( web, name )
        return render_layout( render_hello() .. p.hello( (
    eb.input.greeting or "Hello " ) .. name .. "!" ) )
    end
 
    orbit.htmlify( hello, "render_.+" )
 
    return _M

Now you should be able to launch your web browser and goto http://hostname and you should see “Hello World!”

If you go to http://hostname/index.ws/say/yourname you should see:

“Hello World!
Hello yourname!”

You are done! You can now look at LuaNova’s Orbit Introduction

Today we’re going to talk about a different wombat, with a different destiny.

Spear-headed by Brian McCallister, mod_wombat embeds the Lua programming language into the Apache HTTP server in the same fashion as mod_perl, mod_php and mod_python bring their respective languages into the Apache world of web development.

How mod_wombat differs has a lot to do with how Lua differs from other languages. Lua is a very lightweight scripting language originally designed for non-programmers to customize the software it is embedded in. It is simple to pick up, while offering a good amount of flexibility and power. Its popularity in game scripting has pushed its’ interpreter towards being very efficient and multi-thread ready.

Apache is the heavy-weight champion of HTTP servers, responsible for serving up half the Internet. Apache 2.x was a substantial reworking, providing:

• The Apache Portable Runtime (APR) so Module writers don’t need to deal with all the OS-specific issues.
• Swappable multi-processing modules (MPMs) including Prefork (non-threaded), Worker threads, and an Event MPM that decouples server threads from the HTTP connection (read: very efficient).

Lua is designed for embedding in C-based programs, which allows mod_wombat to take advantage of the substantial infrastructure Apache provides. More than any other language module, mod_wombat endeavors to work with Apache.

Matthew Burke is looking for students to work on mod_wombat as part of the 2008 Google Summer of Code. If you are a student who is interested, you should definitely get in touch with Matthew Burke and Brian McCallister to discuss your ideas. Who knows, this could be your destiny?

This is gonna be great

Lua atop Apache could make for a very sweet development platform for web applications, both large and small.

• Lua is simpler than other scripting languages used for web development, making it easy to pick-up. This is exemplified by the use of tables as a universal data structure (like PHP Arrays, but unlike Python or Ruby).
• Lua has several commonalities with JavaScript, like first-class functions, closures, and prototype-based object orientation. Yet it steps beyond most languages with proper tail calls and coroutines.
• There is a fairly clean slate to start with, meaning it doesn’t carry the baggage of hundreds of procedural methods like PHP, or code mixed into HTML templates. APIs can be nicely organized and designed for simplicity (i.e. ColdFusion’s DateFormat and TimeFormat make it easier to reason about date formatting than Ruby or PHP’s methods).
• Apache’s efficient threading modules combined with Lua’s low-overhead and thread-safety make for a very performant platform. That means it is able to handle a load of traffic without a huge hardware investment.
• Deploying with an Apache module is often the preferred method, as opposed to more complicated reverse proxy setups or FastCGI. For ease of deployment, this is an advantage over the popular Ruby platform, which has no true mod_ruby.
• The mod_wombat project was started by Apache Software Foundation members, is hosted with Apache, and has their backing as a supported module for Apache users.

Ideas

If you are a student joining the GSoC, you will need to come up with your own proposal. I’m not a student, so I don’t qualify, but I will post here a few of the basic ideas that I believe are of general consensus.

Simplify installation

For mod_wombat to become a platform of choice, it needs to be dead-simple to deploy, whether as a development environment or a production server. This would be served by relying only on those modules included with the Apache distribution.

There has been a desire to remove the dependency on libapreg2, which is used to parse HTTP cookies, query-strings and POST data. The required functionality would need to be incorporated into mod_wombat directly.

Tighter integration with Apache HTTP Server 2.2

There is a lot that can be done to further integrate Lua with Apache, whether using Lua to configure Apache, or to pull Apache functionality into Lua.

Perhaps the most significant and obvious, would be integration with Apache’s Database Framework. With DBD, the database drivers for your web application are bundled with Apache, and Apache manages a pool of database connections in an intelligent way appropriate for the MPM being used. With mod_wombat, Lua could be the first language to really take advantage of this feature, new to Apache 2.2.

Write something with it

What mod_wombat provides is an API to higher-level web frameworks and applications. It’s hard to know how those APIs should be written without using them. Building a small project atop mod_wombat could go a long way in designing a concise and friendly API.

Preferably using some sort of code standards.

Resources

If you choose to partake in this endeavor, there a few things you must know.

• Working knowledge of ANSI C, perhaps C: A Reference Manual will help.
• Programming in Lua is an excellent resource for both the Lua programming language and how to interface it with C.
• The Apache Modules Book goes over Apache’s architecture and writing Modules for it, including a chapter on DBD.
• A willingness to work with autoconf and related build tools. There is but one book dedicated to the subject, and the online version is more up-to-date.
• Familiarity with existing web development environments and experience with database systems.
• An understanding of just how Google Summer of Code works.
• Go through Brian’s slides and download the source code from Subversion to familiarize yourself with mod_wombat.

And that’s all there’s to it. Ready to get coding?

Follow-up

Maxime Petazzoni has accepted the role of working on mod_wombat for GSoC this year. See the Apache mailing list.

We haven’t heard a lot about Lua on the web, even though there are a number of developers working with Lua on the server-side. Lets take a brief look.

The Kepler Project

Kepler is a “web development platform” named after astronomer Johannes Kepler. It looks to be the most ambitious project of the bunch. Kepler is written as a number of modules that fit together, and includes its’ own web server named Xavante.

There is also an endeavor to build WSAPI, in similar fashion to Python’s WSGI interface, that support pretty much any web server and configuration (CGI, FastCGI, SCGI, etc, etc.)

Nanoki

When I joined to Kepler mailing list, “Petite Abeille” was the first person to respond. He has been developing a Wiki called Nanoki.

However, it is not built on top of Kepler. Instead there is a small built-in web server or will run atop the Unix tcp command. All the source code is released under a MIT license, and is instructive in building a light, focussed web application vs. the broad scope of Kepler.

mod_wombat

Brian McCallister spear-headed a project to embed Lua in an Apache HTTP Server module. Going through Brian’s slides is quite inspiring as to just how good a fit this is. Apache does all the heavy-lifting, such as providing a fully multi-threaded “worker MPM” (multi-processing module) and a portable runtime (APR) environment. Lua is a thread-safe language, with “share-nothing” Lua states, so it fits right in and is super-efficient.

Skimming through The Apache Modules Book is even more inspiring, as you can see the potential of mod_wombat if it took advantage of Apache’s database connection pooling (DBD) and the various other facilities of Apache HTTP Server.

Wombat is still a little rough around the edges, but you can find the Apache-licensed source code at: http://svn.apache.org/repos/asf/httpd/mod_wombat/trunk.