Unlock High‑Performance Web Services with OpenResty and Lua: A Complete Guide

Overview

OpenResty is a high‑performance web platform built on Nginx and Lua, integrating many Lua libraries, third‑party modules and dependencies. It enables building dynamic web applications, services and gateways that handle massive concurrency and scale.

OpenResty runs web services inside Nginx, leveraging its non‑blocking I/O model not only for HTTP requests but also for backend services such as MySQL, PostgreSQL, Memcached and Redis.

There are two branches: the open‑source free “OpenResty” and the commercial “OpenResty+”, supported by the community, the OpenResty Foundation, OpenResty.Inc and sponsors like Kong and CloudFlare.

Official site: http://openresty.org/

Dynamic Lua Scripts

A key module in OpenResty is ngx_lua, which brings the Lua scripting language into Nginx. Lua is a small, fast language designed to be embedded, often used as a “glue language” in games such as World of Warcraft and Angry Birds.

OpenResty adopts Lua because writing Nginx modules in C is cumbersome; Lua provides a fast scripting layer without significant performance loss.

Lua supports hot‑loading: code can be reloaded from disk, Redis, or other sources without restarting the process, allowing micro‑second configuration changes.

Efficient Lua Scripts

OpenResty’s performance relies on a “synchronous non‑blocking” programming model built on Lua coroutines, which act as user‑space multiplexing, consuming fewer resources than kernel‑level epoll.

Each Lua chunk runs in a coroutine; when a potential block occurs the coroutine yields, allowing other coroutines to run. The whole system remains non‑blocking while individual flows may block.

Example: read POST body and echo it back

ngx.req.read_body()  -- synchronous non‑blocking (1)

local data = ngx.req.get_body_data()
if data then
    ngx.print("body: ", data)  -- synchronous non‑blocking (2)
end

ngx.req.read_body

and ngx.print are synchronous I/O operations; however, OpenResty does not block the whole worker. If the network is slow, the coroutine yields and the CPU can handle other requests.

For a 10 ms network wait and only 0.1 ms CPU time, OpenResty can serve 100 requests in that 10 ms window instead of queuing them for a full second.

OpenResty also uses LuaJIT, which compiles Lua to native machine code and provides extensions such as the bit library, table optimizations, and FFI for direct C calls, making Lua scripts run as fast as C.

Installing OpenResty

Chinese site: https://openresty.org/cn/

Prerequisites

Install perl ≥5.6.1, libpcre, libssl and ensure ldconfig can locate them. Debian/Ubuntu users can run:

apt-get install libpcre3-dev libssl-dev perl make build-essential curl

Building OpenResty

Download the latest source tarball, extract it, then configure, compile and install:

wget https://openresty.org/download/openresty-1.25.3.1.tar.gz

tar -xzvf openresty-1.25.3.1.tar.gz

cd openresty-1.25.3.1

./configure
# optional flags, e.g.:
# ./configure --prefix=/opt/openresty \
#   --with-luajit \
#   --without-http_redis2_module \
#   --with-http_iconv_module \
#   --with-http_postgres_module

make
make -j2   # if you have multiple cores
make install

After installation, add OpenResty binaries to PATH, e.g.:

export PATH=/usr/local/openresty/bin:/usr/local/openresty/nginx/sbin:$PATH

Test the installation with:

/usr/local/openresty/nginx/sbin/nginx -v

Setting Up Service and Autostart

Create a systemd unit file at /etc/systemd/system/openresty.service:

[Unit]
Description=A dynamic web platform based on Nginx and LuaJIT.
After=network.target

[Service]
Type=forking
PIDFile=/run/openresty.pid
ExecStartPre=/usr/local/openresty/bin/openresty -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/local/openresty/bin/openresty -g 'daemon on; master_process on;'
ExecReload=/usr/local/openresty/bin/openresty -g 'daemon on; master_process on;' -s reload
ExecStop=-/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/openresty.pid
TimeoutStopSec=5
KillMode=mixed

[Install]
WantedBy=multi-user.target

Reload systemd, start and enable the service:

systemctl daemon-reload
systemctl restart openresty
systemctl enable openresty
systemctl status openresty.service

The status output confirms a successful installation.

References

[1] OpenResty: https://openresty.org/cn/openresty.html