Introduction to lapis


Introduction to lapis

Lapis is a web framework written for Lua and moonscript. Lapis is interesting because it’s built on top of openresty released by nginx. Your web application runs directly inside nginx. Nginx’s event loop allows you to use openresty provided modules for asynchronous HTTP requests, database queries, and other requests. Lua’s orchestration allows you to write event driven synchronization code in the background. In addition to providing a web framework, lapis also provides tools for controlling openresty in different configuration environments. Even if you don’t want to use the web framework, if you use openresty, you may find it still useful.

This web framework implements the active recording system supported by URL router, HTML template, CSRF and session support, PostgreSQL or mysql, which is used to process model and develop some other useful functions required by website.

This guide is expected to serve as a tutorial and reference for you

Basic settings

Install openresty on the system. If you use heroku, you can use the heroku openresty module and Lua build package.

Using lualocks to install lapis

luarocks install lapis

Create an app

Lapis command line tool

Lapis comes with a command-line tool that helps you create new projects and start servers. To see what lapis can do, run it in your shelllapis help

Now, we will create a new project. Switch to a clean directory and run the following command:

lua new
wrote   nginx.conf
wrote   mime.types
wrote   app.moon

Lapis writes a basic nginx configuration and a blank Lapis application.

Check the generated configuration file at will (nginx.conf is the only important file). Here is a brief overview of its features:

Any request in / static / will provide static files (you can create this directory if you want to provide this function)

The request for / favicon.ico responds to the file / static / favicon.ico

All other requests will then be provided by Lua, more specifically a module called “app”

When you start the server using the Lapis command-line tool, the nginx.conf file is processed and the template variables are populated with values from the current Lapis environment. This will be discussed in more detail below.

Nginx configuration

Let’s seelapis newGive us the configuration. While it’s not necessary to look at it immediately, it’s important to understand it if you want to build a more advanced application or even just want to deploy it to a production environment.

This is generatednginx.conf

worker_processes ${{NUM_WORKERS}};
error_log stderr notice;
daemon off;

events {
  worker_connections 1024;

http {
  include mime.types;

  server {
    listen ${{PORT}};
    lua_code_cache ${{CODE_CACHE}};

    location / {
      default_type text/html;
      content_by_lua '

    location /static/ {
      alias static/;

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

The first thing to note is that this is not a normal nginx configuration file. Lapis uses special${{VARIABLE}}Syntax inject environment settings before starting the server.

error_log stderr noticeanddaemon offLet our server run in the foreground and print the logs to the console. This is good for development, but it must be closed during production

lua_code_cacheIt is also a useful setting for development. When set tooffWill cause allLuaThe module reloads on each request. Changes to the source code of a web application can be automatically overloaded. In a production environment, you should enable(on)Cache for best performance. Default isoff

content_by_luaInstruction specifies aLuaCode block, which will handlelocationAny requests that do not match. It loadsLapisAnd tell it it’s calledappThe module of provides services. Previously runlapis newProvides a framework moduleappLet’s start

Start server

Although it can be started manuallyNginx, butLapisA convenient command is wrapped to build the configuration and start the server.

stayshellRunning inlapis serverThe server will start.LapisWill try to find your openresty installation. It will search for nginx binaries in the following directories. (the last one represents anything in your path)

Remember, you need openresty instead of installing nginx properly. Lapis will ignore the regular nginx binaries.

Continue and start the server to see what it looks like:
lapis server

The default configuration will put the server in the foreground and use Ctrl + C to stop the server.
If the server is running in the background, you can use thelapis termstop it. It must run in the root of the application. This command finds the PID file of the running server and sends it to the processTERMMessage (if present)

Create an app

Now that you know how to build a new project and start and stop the server, you are ready to start writing application code. This guide is divided intoMoonScriptandLuaTwo.

If you’re not sure what to use, I suggest reading through two paths.

Create an application with Lua
Create an application with MoonScript