Getting Started With Lapis

Lapis is a web framework written for Lua and MoonScript. Lapis is designed with performance in mind so by default it runs configured for the Nginx distribution OpenResty. Your web application is run directly inside of Nginx. Nginx’s event loop lets you make asynchronous HTTP requests, database queries and other requests using the modules provided with OpenResty. Lua’s coroutines allow you to write synchronous looking code that is event driven behind the scenes.

The web framework comes with an environment based configuration, URL routing, HTML templating, CSRF and session support, a relational database object relational mapper for working with models and a handful of other useful functions needed for developing websites and more.

This introduction guide functions as both a tutorial and a reference.

Basic Setup

Lapis is easiest to use within a system with LuaRocks installed. LuaRocks is the most common package manager for Lua.

The first step is to install Lapis via LuaRocks:

$ luarocks install lapis

OpenResty is designed for LuaJIT which targets Lua 5.1. If you plan to only use OpenResty, then in order to ensure that OpenResty is able to load Lapis within its own runtime you will want to install Lapis targeting Lua 5.1. You can use the --lua-version=5.1 flag with LuaRocks to accomplish this.

Creating An Application

`lapis` Command Line Tool

Lapis comes with a command line tool to help you create new projects and start the server. To see what Lapis can do, run in your shell:

$ lapis help

The lapis new command can be used to start a new project. First run lapis help new to learn more about the command line arguments the command can use.

For simplicity, in this guide we'll generate a new app with all the defaults. Navigate to an empty directory where you want to keep your project and run the following:

$ lapis new

write  config.lua
write  nginx.conf
write  mime.types
write  app.lua
write  models.lua

If you wish to continue this guide without OpenResty, you can run lapis new --cqueues.

When generating a new project for OpenResty, a configuration file, a basic Nginx configuration, a blank Lapis application, and a models module that autoloads your models from the models directory are written.

Here’s a brief overview of the default nginx.conf

Any requests inside /static/ will serve files out of the directory static (You can create this directory now if you want)
A request to /favicon.ico is read from static/favicon.ico
All other requests will be served by Lua, more specifically a module named "app"

When you start the server using the lapis server command the nginx.conf file is processed and templated variables are filled with values from the configuration generated by the environment. This is discussed in more detail further on.

Nginx Configuration

Let’s take a closer look at the Nginx configuration that lapis new has given us. Although it’s not necessary to look at this immediately, it’s important to understand when building more advanced applications or even just deploying your application to production.

Here is the nginx.conf that has been generated:

worker_processes ${{num_workers}};
error_log stderr notice;
daemon off;
pid logs/nginx.pid;

events {
  worker_connections 1024;
}

http {
  include mime.types;

  init_by_lua_block {
    require "lpeg"
  }

  server {
    listen ${{port}};
    lua_code_cache ${{code_cache}};

    location / {
      content_by_lua_block {
        require("lapis").serve("app")
      }
    }

    location /static/ {
      alias static/;
    }

    location /favicon.ico {
      alias static/favicon.ico;
    }
  }
}

The first thing to notice is that this is not a normal Nginx configuration file. Special ${{variable}} syntax is used by Lapis to inject values from your configuration before starting the server. See Configurations and Nginx for more details.

There are a couple interesting things provided by the default configuration. error_log stderr notice and daemon off lets our server run in the foreground, and print log text to the console. This is great for development, but worth turning off in a production environment.

lua_code_cache is also another setting useful for development. When set to off it causes all Lua modules to be reloaded on each request. Modifications to the web application’s source code can then be reloaded automatically. In a production environment the cache should be enabled (on) for optimal performance. The generated config.lua sets it to off for the development environment.

The content_by_lua_block directive specifies a chunk of Lua code that will handle any request that doesn’t match the other locations. It loads Lapis and tells it to serve the module named "app". The lapis new command ran earlier provides a skeleton app module to get started with.

Starting The Server

Although it’s possible to start Nginx manually, Lapis wraps building the configuration and starting the server into a single convenient command.

Running lapis server in the shell will start the server. Lapis will attempt to find your OpenResty installation. It will search the following directories for a binary named nginx or openresty. (The last one represents anything in your PATH)

"/opt/openresty/nginx/sbin/"
"/usr/local/openresty/nginx/sbin/"
"/usr/local/opt/openresty/bin/"
"/usr/sbin/"
""

If your OpenResty is installed somewhere else, set the LAPIS_OPENRESTY environment variable to the path of the binary.

Remember that you need OpenResty and not a normal installation of Nginx. Lapis will ignore regular Nginx binaries.

If you've been following along, go ahead and start the server to see what it looks like:

$ lapis server

The default configuration puts the server in the foreground, use CTRL+C to stop the server.

If the server is running in the background it can be stopped with the command lapis term. It must be run in the root directory of the application. This command looks for the PID file for a running server and sends a TERM message to that process if it exists.

Writing Application Code

Now that you know how to generate a new project and start and stop the server you're ready to start writing application code. This guide splits into two for Lua and MoonScript.

Lapis