Gremoire

🔧 How to Compile Nginx with Lua Support (ngx_http_lua_module) ​

A complete step-by-step guide to building a custom Nginx with Lua scripting support for advanced middleware, dynamic configuration, and API logic.

Overview ​

By default, the standard Nginx package from most Linux distributions does not include the Lua module.
To enable Lua scripting (e.g., content_by_lua_block or access_by_lua_file), you need to compile Nginx manually with:

  • ngx_devel_kit (NDK)
  • ngx_http_lua_module
  • (Optional) SSL and PCRE for HTTPS and regex support

This guide covers how to do that cleanly on Ubuntu/Debian or any Linux environment.

Prerequisites ​

Before compiling, install the required build tools and dependencies.

bash
sudo apt update
sudo apt install -y build-essential libpcre3-dev zlib1g-dev libssl-dev liblua5.1-dev git curl

Tip: Lua 5.1 is recommended because ngx_http_lua_module is built on LuaJIT 2.x, which maintains backward compatibility with Lua 5.1 syntax.

Step 1 — Download Nginx Source ​

Choose the version you want (for example, 1.29.2):

bash
cd /usr/local/src
curl -O http://nginx.org/download/nginx-1.29.2.tar.gz
tar -zxvf nginx-1.29.2.tar.gz
cd nginx-1.29.2

Step 2 — Clone Required Modules ​

Clone both NDK (Nginx Development Kit) and the Lua module.

bash
cd /usr/local/src
git clone https://github.com/simplresty/ngx_devel_kit.git
git clone https://github.com/openresty/lua-nginx-module.git

Step 3 — Configure Nginx with Lua Support ​

You can either build a dynamic module (recommended) or a statically compiled one.

Option A: Build as Dynamic Modules ​

This keeps Nginx core clean and allows you to load/unload Lua later.

bash
cd /usr/local/src/nginx-1.29.2

./configure   --prefix=/etc/nginx   --sbin-path=/usr/sbin/nginx   --conf-path=/etc/nginx/nginx.conf   --pid-path=/var/run/nginx.pid   --modules-path=/etc/nginx/modules   --with-http_ssl_module   --with-http_v2_module   --with-http_stub_status_module   --add-dynamic-module=../ngx_devel_kit   --add-dynamic-module=../lua-nginx-module

Then compile only the modules:

bash
make modules

This will generate:

objs/ndk_http_module.so
objs/ngx_http_lua_module.so

Move them into your Nginx modules folder:

bash
sudo cp objs/*.so /etc/nginx/modules/

Then load them inside your main nginx.conf:

nginx
load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;

Option B: Compile into Nginx Binary (Static) ​

If you prefer a single binary build:

bash
./configure   --prefix=/etc/nginx   --add-module=../ngx_devel_kit   --add-module=../lua-nginx-module   --with-http_ssl_module   --with-http_v2_module

make
sudo make install

Step 4 — Verify Lua Module Loaded ​

Check if Lua is included:

bash
nginx -V 2>&1 | grep lua

Expected output (example):

--add-dynamic-module=../lua-nginx-module

If using dynamic loading:

bash
sudo nginx -t

You should not see any module loading errors.

Step 5 — Test Lua in Nginx ​

Create a simple Lua-powered route:

bash
sudo tee /etc/nginx/conf.d/lua_test.conf > /dev/null <<'EOF'
server {
    listen 8080;

    location /lua {
        default_type text/plain;
        content_by_lua_block {
            ngx.say("Hello from Lua! Time: ", ngx.localtime())
        }
    }
}
EOF

Reload Nginx:

bash
sudo nginx -s reload

Now test:

bash
curl http://localhost:8080/lua

Output:

Hello from Lua! Time: 2025-10-15 16:42:00

Success! Lua is now fully integrated with your Nginx build.

Step 6 — Lua File Loading Example ​

You can also store Lua scripts in files:

bash
/etc/nginx/lua/hello.lua
lua
ngx.say("Greetings from an external Lua file!")

Use it in Nginx:

nginx
location /file-test {
    content_by_lua_file /etc/nginx/lua/hello.lua;
}

Bonus — Recompiling Quickly ​

To rebuild later (e.g., for updates):

bash
cd /usr/local/src/nginx-1.29.2
make clean
make modules
sudo cp objs/*.so /etc/nginx/modules/
sudo nginx -s reload

Troubleshooting ​

ProblemSolution
nginx: [emerg] unknown directive "content_by_lua_block"Lua module not loaded — ensure load_module lines are in the main nginx.conf.
undefined symbol: ndk_set_var_valueMissing NDK — ensure load_module modules/ndk_http_module.so; is above Lua module load.
lua_load_resty_core failedLuaJIT not found — ensure liblua5.1-dev or luajit is installed.
ABI mismatch (apt errors)Don’t mix repository modules with custom-built Nginx — compile everything from source.

Optional: Install LuaRocks (Lua Package Manager) ​

If you want to use external Lua libraries:

bash
sudo apt install luarocks
sudo luarocks install lua-cjson
sudo luarocks install luasec

Then in Nginx Lua code:

lua
local cjson = require "cjson"
ngx.say(cjson.encode({ status = "ok" }))

Conclusion ​

You now have a custom Nginx build with full Lua scripting power — perfect for:

  • Building middleware filters
  • Implementing API gateways
  • Performing security checks
  • Writing custom authentication logic
  • Hiding framework fingerprints (React, Vue, etc.)

For even more power, check out:

Author: Cloud Developer
Last updated: October 2025
License: MIT