# OpenResty — High-Performance Web Platform on Nginx + Lua

> OpenResty bundles Nginx with LuaJIT and dozens of Lua modules to turn the world's most proven reverse proxy into a full-blown application server for gateways, edge APIs, and WAFs.

## Install

Save in your project root:

# OpenResty — High-Performance Web Platform on Nginx + Lua

## Quick Use
```bash
# Install on Ubuntu/Debian
wget -qO - https://openresty.org/package/pubkey.gpg | sudo apt-key add -
echo "deb http://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list
sudo apt update && sudo apt install -y openresty

# Minimal Lua handler in nginx.conf
server {
  listen 8080;
  location /hi {
    content_by_lua_block { ngx.say("hello from openresty") }
  }
}
sudo openresty -s reload
curl localhost:8080/hi
```

## 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/

---
Source: https://tokrepo.com/en/workflows/6b536a71-3908-11f1-9bc6-00163e2b0d79
Author: AI Open Source