OpenResty — High-Performance Web Platform on Nginx + Lua

Introduction

OpenResty extends Nginx with LuaJIT, the ngx_lua module, and dozens of curated Lua libraries — cosockets, DNS, Redis, MySQL, OAuth, JSON, JWT, and more. The result is a web platform that keeps Nginx's event-driven performance (tens of thousands of connections per core) while letting you write request handling in high-level Lua. It's the foundation of Apache APISIX, Kong, and every major open source API gateway. Over 13,000 GitHub stars on the parent repo.

What OpenResty Does

• Embeds LuaJIT inside every Nginx worker for near-C performance.
• Exposes non-blocking cosocket APIs for Redis, MySQL, HTTP, DNS, and more.
• Hooks at every Nginx phase: access, rewrite, content, header_filter, body_filter, log, balancer.
• Ships resty-cli for running Lua scripts outside Nginx with the full stdlib.
• Runs on the same single-binary deploy model as stock Nginx.

Architecture Overview

OpenResty patches Nginx with ngx_lua and ships a curated set of C and Lua modules. Each worker has its own LuaJIT VM with shared dictionaries (lua_shared_dict) for inter-worker state. Because LuaJIT is JIT-compiled to machine code, handlers run at near-C speed while staying fully non-blocking — cosockets yield back to the Nginx event loop whenever they'd block. Timers and background tasks run via ngx.timer.at. You can precompile Lua with lua_code_cache on.

Self-Hosting & Configuration

• Install the official package on Ubuntu/Debian/RHEL/Alpine, or use the openresty/openresty Docker image.
• Point lua_package_path at your Lua modules and drop handlers in content_by_lua_file or access_by_lua_file.
• Use lua_shared_dict for rate limiting, caching, and session data across workers.
• Reach for lua-resty-* libraries — lua-resty-redis, lua-resty-mysql, lua-resty-http, lua-resty-jwt.
• Deploy with openresty -t for config test, then openresty -s reload for zero-downtime reloads.

Key Features

• Nginx performance + Lua productivity in a single binary.
• Rich resty.* library ecosystem covering most backend integrations.
• Shared memory zones for in-process caching and rate limiting.
• Used in production by Cloudflare, Fastly-era Akamai Bot Manager, and major CDNs.
• The foundation for Apache APISIX, Kong Gateway, 3scale APIcast, and more.

Comparison with Similar Tools

• Plain Nginx + NJS — Nginx's native JS module; smaller ecosystem, less mature than ngx_lua.
• HAProxy + Lua — HAProxy has a Lua core; fewer modules, weaker HTTP feature set.
• Envoy — C++ proxy with WASM extensions; better xDS story, steeper learning curve.
• Caddy — Go-based server with plugins; easier config, less raw throughput at the high end.
• API gateways (Kong, APISIX) — built on top of OpenResty; pick them when you need a full control plane.

FAQ

Q: Can I reuse my existing nginx.conf? A: Yes — OpenResty is a strict superset; point it at your existing config and it just works.

Q: What Lua version is used? A: LuaJIT 2.1 with OpenResty's extensions. Standard Lua 5.1 code runs as-is.

Q: Does it support HTTP/3? A: Yes, via the QUIC-capable Nginx core; some features are still labeled experimental.

Q: How do I debug Lua handlers? A: Use ngx.log(ngx.ERR, ...) for structured logs and resty --stap with SystemTap for deep profiling.

Sources

• https://github.com/openresty/openresty
• https://openresty.org/en/