Today I’m going to show you how to write your own Lua module in an OpenResty application, step by step.

Let’s put our simple OpenResty application in a new directory called test-module.

cd ~/
mkdir test-module/
cd test-module/

Then we create the subdirectory structure as usual.

mkdir logs conf lua

Note that unlike the “Hello World” example in the previous tutorial, we have created a lua/ directory to hold our Lua module files.

Now let’s create our own Lua module file in the Lua subdirectory, called hello.lua.

vim lua/hello.lua

We did the following editing:

  1. Declare the Lua module table_M.
  2. Then add a name to the Lua modulegreetThe function.
  3. Finally, don’t forget to return the module table at the end.
local _M = {}

function _M.greet(name)
    ngx.say("Greetings from ", name)

return _M

Done! A very simple Lua module is complete.

Now it’s time to create the nginx.conf configuration file.

vim conf/nginx.conf

We quickly completed the following editing operations:

  1. Let’s quickly write out a relatively fixed configuration.
  2. inhttp {}In the configuration block, we should tell OpenResty where our Lua module is located.
  3. Please note that special variables$prefixNginx at run time-pThe option value is replaced.
  4. Then we create an HTTP server and listen on port 8080.
  5. And configured at the root locationcontent_by_lua"_block.
  6. Here we userequireBuilt-in functions load Lua moduleshello.
  7. We call it with an argumentgreetFunction.
worker_processes 1; events { worker_connections 1024; } http { lua_package_path "$prefix/lua/? .lua;;" ; server { listen 8080 reuseport; location / { default_type text/plain; content_by_lua_block { local hello = require "hello" hello.greet("a Lua module") } } } }

Let’s examine the entire directory tree now.

tree .

screenshot 22

It looks good.

Now start the OpenResty application.

nginx -p $PWD/

It is time to usecurlThe command line tool queried our HTTP interface.

The curl ''

Cool, our Lua module is working.

We can also test it in a web browser.

If you see 500 error pages, there must be something wrong with your Lua code.

In this case, you should check the error.log file in the logs subdirectory.

tail logs/error.log

We don’t have any error messages here, as would be expected.

It is worth noting that our Lua module is loaded in this first request, and subsequent requests simply use the Lua module cached in memory. To avoid the extra overhead of the first request, we can preload the Lua module when the server starts.

To do this, we need to edit the nginx.conf file.

vim conf/nginx.conf

Within the HTTP {} block, we add an init_by_lua_block directive. In that context, we load our Lua module.

    http {
        init_by_lua_block {
            require "hello"

The init_by_lua_block runs when the OpenResty server is started.

Test that the configuration is correct.

nginx -p $PWD/ -t

No problem.

Now let’s reload the server by sending a HUP signal to the main nginx process. Now we reload the server by sending the HUP signal to the nginx master process.

kill -HUP `cat logs/`

The process ID of the main process is stored in this file.

Send the HTTP request again.

The curl ''

Same behavior, just a little faster this time. If you enjoyed this tutorial, please subscribe to this blog site and our YouTube channel or Station B channel. Thank you very much!

About this article and associated videos

This article and the associated videos were generated entirely automatically by our OpenResty Demo system from a very simple script file.

About the author

Yicchun Zhang is the founder of OpenRESTY ®, an open source project, and OpenRESTY Inc. Founder and CEO of the company. He has contributed many third-party modules for Nginx, quite a few Nginx and Luajit core patches, and has designed products such as OpenResty Xray.

Pay attention to our

If you enjoyed this article, please follow our blog at OpenResty Inc. Also welcome to scan the code to pay attention to our WeChat official account:


We have provided the original English and Chinese versions (this article). We also welcome readers to provide translations in other languages. As long as the full text is translated without omission, we will consider using it. Thank you very much!