Lapis

v1.20.0
Lua MoonScript

Server Backends

All Guides

Server Backends

Lapis is a web framework, it does not provide an HTTP server implementation. A separate server must be used, and Lapis must know how to communicate with it. Lapis supports the following servers:

Lapis will only support servers that enable non-blocking IO transparently through coroutines. You can learn more about what this means in itch.io and coroutines.

Which Server to Use?

Lapis was originally designed for OpenResty. We've been running it in production for many years with great success. It’s stable, fast, and actively developed.

Nginx, the server that OpenResty provides, is a great tool for a wide range of things: serving static files, setting up a reverse proxy, security configuration, rate limiting, scaling to multiple cores.

OpenResty’s Lua API provides a handful of things that you may find useful as well: common hashing functions, a system for asynchronous tasks, shared memory.

There are a few disadvantages: It can not be installed with LuaRocks, so you'll need to install it manually. Additionally, Nginx requires a separate configuration language.

cqueues is a more recent addition. The main advantage is that it’s a Lua library, so you can install it with LuaRocks. It’s easier to get started if you have a working LuaRocks installation, and it has a much more flexible event loop. However, it doesn’t provide many of the things that Nginx provides, so you'll have to provide Lua based implementations. Additionally, at the moment Lapis only knows how to run it in a single process, on a single core.

golapis is an experimental server written in Go that embeds LuaJIT and implements the ngx API from OpenResty. Lapis runs on it using the same code path as OpenResty, so no changes to your application are needed. It’s a single binary with no dependency on Nginx, which makes it easy to get started with. It is early in development, so expect missing features. See Running on golapis below.

Can I switch between the servers?

The Lapis API does not change depending on the server you're using, but Nginx requires its own configuration file. If you instruct Nginx to do certain things in that file then a cqueues server will not be aware. In order to have server swapping it’s recommended to implement as much of your application in Lua using Lapis APIs as possible.

Some features are currently only available with OpenResty:

Specifying a Server

You can specify which server to use in your configuration file:

-- config.lua
local config = require("lapis.config")

config("development", {
  server = "cqueues"
})

-- config.moon
config = require "lapis.config"

config "development", ->
  server "cqueues"

The cqueues server binds to the address set by the bind_host configuration value, which defaults to "0.0.0.0".

Running on golapis

golapis is experimental and early in development. Not every ngx API that Lapis or other libraries depend on is implemented yet. Check the golapis README for what is supported.

golapis is built from source, which requires Go and a C compiler:

$ git clone --recursive https://github.com/leafo/golapis.git
$ cd golapis
$ make install

golapis isn’t started with lapis server, instead you run the golapis binary directly with an entry file. The entry file serves your application the same way the nginx.conf generated by lapis new does:

-- serve.lua
require("lapis").serve("app")

Start the server with the --http flag. The --ngx flag is required, it makes the golapis API available as the ngx global that Lapis uses:

$ golapis --http --ngx --port 8080 serve.lua

Because golapis runs your application with the same code path as OpenResty, leave the server configuration value as "nginx". There is no nginx.conf, so anything configured there is instead passed as command line flags. For example, to serve a static directory and create the page_cache shared dictionary used by the cache module:

$ golapis --http --ngx --port 8080 \
  --file-server static \
  --shared-dict page_cache:15m \
  serve.lua

The entry file can also be written in MoonScript, eg. serve.moon. golapis will compile it, along with any MoonScript modules it requires, when they are loaded.