Lua has been of interest to me recently, and when I started designing this site it didn't take me long to decide that I wanted to try using Lua to make it. The Lua language is small, fast (for a language that is referred to as a "scripting" language), and has good text manipulation faculties, so it would seem to be a good fit for a web app. The only slight issue with having such a small language is that not a whole lot is built in. Even doing anything with a filesystem any more advanced than a file read or a write isn't present in Lua. This is where Kepler steps in.

Kepler describes itself as:

A Lua web development platform that offers the same advantages of Lua. Kepler is simple, portable, light, embeddable and extensible.

But I would have to say that at best they're being modest and at worst they're being incredibly non-specific.

I would say that Kepler is Lua with Batteries Included, for the web. Alex, didn't you just repeat what they said but with a meaningless buzz-phrase? Why yes, I did. But to me this statement caries a little more weight behind it because it implies what Kepler really is: A "one-click" install that includes Lua itself, a packaging system, libraries that would usually be considered to be in the domain of standard libraries, a CGI interface (optionally fastcgi or mod_lua, an Apache module), a template system, and even a native Lua web server just in case you wanted one. Check out the list of components for a more in depth look at these features. The fact that Lua itself as well as LuaRocks (the packaging system) are included in the Kepler installer is oddly not remotely emphasized on the Kepler site. To me this is a major feature of their platform.

The rest of this tutorial will go attempt to explain in detail what one has to go through in order to set up Kepler, base on my experience of installing it on my web host, Dreamhost. It assumes the user is running a unix-like environment and has a semi-basic grasp of the command line.

The first thing you need to do is to log into your server. This can be done remotely via the command line using ssh.

ssh username@example-site.com

You will be prompted for your password, and then afterwards you should be greeted with a prompt from your server.

Now you have a choice. You could either choose to install Kepler in your home directory or in its own directory. I chose to keep it confined to its own directory:

mkdir kepler
cd kepler

If you wanted Kepler installed in your home directory, just skip that step.

Now we download the Kepler installer. As of the time of writing the most recent version was 1.1.1-2, although I recommend checking for newer versions on LuaForge.

wget http://luaforge.net/frs/download.php/4017/kepler-install-1.1.1-2

This is where the magic happens. First we modify the permissions of the Kepler installer to allow it to be executed, then we execute it with the desired point of installation specified in the flag --prefix. My server at Dreamhost doesn't have the library Readline installed so I had to disable it with a flag. This is fine, since it is only used for making the Lua prompt a little nicer to work with and you'll probably never have to directly use the Lua prompt on your server anyways. Remember that if you wanted to install Kepler in your home directory, you'll have to omit the /kepler from the code below.

chmod +x kepler-install-1.1.1-2
./kepler-install-1.1.1-2 --without-readline --prefix=$HOME/kepler

It'll take a few minutes to complete and when you're done you'll have Lua and Kepler installed on your server. The only thing left in order to finish the install is to make it so that your programs know where to find the programs you just installed.

cd
echo "export PATH=$PATH:$HOME/kepler/bin" >> .bash_profile

And that will do it. If you source .bash_profile you should be able to type lua at the command line and get a Lua prompt. Ctrl-C will get you out of that prompt.

Now that Kepler is good to go, we need to set things up so that you can start making programs that will serve up web pages based on the urls that people request. To do this we must properly set up cgilua.cgi and .htaccess. Where you're allowed to put CGI scripts varies from one host to another. I'm not aware of any particular restrictions for Dreamhost, so I chose to put it in my site's root directory. This directory is where the server looks for files when a url is requested. For me it is the directory alex-charlton.com/ which is located in my home. The permissions of cgilua.cgi must also be set to allow for execution.

cp ~/kepler/bin/cgilua.cgi ~/alex-charlton.com/
cd alex-charlton.com
chmod 711 cgilua.cgi

This is where things enter into the relm of a personal hack. You are of course free to set up cgilua.cgi and .htaccess however you please. If you want things to work for blog.lua you'll have to do things as I describe. I also feel that the way I did things simplifies matters quite a bit, although that may well just be me. Whatever you choose to do at this point, just know that this is not the kosher way of doing things. Check out the Kepler installation page for their approach.

Personally, I feel that the cleanest way to organize a website is to send all requests to one file. In this case it would be a Lua file. This dispatch file then chooses what to do based on the url requested. In order to achieve this we will create a dispatch file and point cgilua.cgi to that file. This will involve editing cgilua.cgi, something I've avoided up to this point. If you've never used a command line editor before, I recommend Pico, which should be installed on most unix machines.

touch dispatch.lua
pico cgilua.cgi

This will throw you into the pico editor. On the last line you should see something like:

exec "/home/username/- ... -/bin/cgilua.cgi" "$@"

Change it to:

exec "/home/username/- ... -/bin/cgilua.cgi" "dispatch.lua" "$@"

And save and quit the file (Ctrl-O, Enter, Ctrl-X).

From here we need to create an .htaccess file that will redirect your trafic to cgilua.cgi. It is important however not to direct requests for images or css files to your dispatch file, unless you want to have to deal with those requests. My method for circumventing this is to make a directory for things that we'll instruct .htaccess not to touch. On my site, I call this folder media/.

mkdir media
pico .htaccess

Again we find ourselves in the Pico editor. Add the following lines:

RewriteEngine On
RewriteBase /
RewriteRule ^(media/?.*)$ - [L]
RewriteRule ^cgilua\.cgi/(.*) - [L]
RewriteRule ^(.*)$ cgilua.cgi/?$1 [L]

Save and quit again.

We're on the home stretch. We now only need to make our dispatch script do something. pico dispatch.lua and insert the following:

url = arg[2] or "The home page"
cgilua.htmlheader()
cgilua.put("Welcome! The url you requested is: ", url)

After you save, when you navigate to your website you'll be greeted with the page you're trying to get to. Because we configured .htaccess and cgilua.cgi in my weird way we are able to access the part of the url (after your domain name) that was requested in the global variable arg[2]. Clearly this is not the most useful site in the world, but add a bit of imagination and Lua code and you'll be well on your way to yummy dynamic content!

If you're interested in setting up a blog in a hurry, blog.lua is a good place to start. Otherwise, reading the Kepler documentation, specifically that of CGILua and its LuaPages, will get you on the right track. If you need a little help with the Lua language, try reading Programming in Lua. There's always the Lua Reference Manual and Lua User's Wiki too.