Using Lua Nginx module for dynamic routing based on Redis values

Working with Nginx modules can bring amazing flexibility to customize and make the Nginx server more powerful by using third-party modules, but the struggle is to actually get these things working together. By the end of this article, you should be able to build and run Nginx server on Ubuntu 20.04 and use “User-Agent” header from the incoming request to route it to different HTTP backend based on Redis store values.

This article assumes that you have fundamental knowledge working with Nginx.
There are two ways to get Nginx up and running:
1. Install Nginx as a prebuilt-package
2. Build Nginx from the source with other modules (an approach we are following in this article)

I. Installing Required Packages:

1. Tool required to build modules and Nginx from the source
$ sudo apt-get install build-essential
2. Libraries needed by nginx
$ sudo apt-get install libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev
3. Caching store we are fetching values from
$ sudo apt-get install redis-server 
4. Curl to test the nginx http routes
$ sudo apt-get install curl

II. Downloading source files for Nginx and Modules:

We are downloading the open-source version of Nginx - nginx.org, often confused with the paid platform - nginx.com.

1. Create your working directory named “nginx”.
$ mkdir /home/<user>/nginx 
$ cd /home/<user>/nginx
2. Download source files:
- Nginx source
$ wget http://nginx.org/download/nginx-1.17.0.tar.gz 
- Just-In-Time Compiler for Lua
$ wget http://luajit.org/download/LuaJIT-2.0.5.tar.gz 
- Module designed to extend the core functionality of Nginx
$ wget -O nginx_devel_kit.tar.gz https://github.com/simpl/ngx_devel_kit/archive/v0.3.0.tar.gz 
- Lua module for nginx 
$ wget -O nginx_lua_module.tar.gz https://github.com/openresty/lua-nginx-module/archive/v0.10.14.tar.gz
- Lua module to connect to redis
$ wget -O lua-resty-redis-0.29 https://github.com/openresty/lua-resty-redis/archive/refs/tags/v0.29.tar.gz

III. Extracting the source files using the following commands

$ tar -zxvf LuaJIT-2.0.5.tar.gz
$ tar -zxvf nginx-1.17.0.tar.gz
$ tar -zxvf nginx_devel_kit.tar.gz
$ tar -zxvf nginx_lua_module.tar.gz
$ tar -zxvf lua-resty-redis-0.29.tar.gz

IV. Building LUAJIT and Nginx

$ cd /home/<user>/nginx/LuaJIT-2.0.5
$ make install

Configuring the nginx source code to run with the modules. To do this, run the ./configure script from nginx source code installation folder. ./configure script also gives the errors for any missing libraries which can be installed using “sudo apt-get install …”

$ cd /home/<user>/nginx/nginx-1.17.0
$ LUAJIT_LIB=/usr/local/lib LUAJIT_INC=/usr/local/include/luajit-2.0 
 ./configure 
 — sbin-path=/usr/sbin/nginx 
 — conf-path=/etc/nginx/nginx.conf 
 — error-log-path=/var/log/nginx/error.log 
 — http-log-path=/var/log/nginx/access.log 
 — with-pcre 
 — pid-path=/var/run/nginx.pid 
 — with-http_ssl_module 
 — add-module=/home/<user>/nginx/ngx_devel_kit-0.3.0 
 — add-module=/home/<user>/nginx/lua-nginx-module-0.10.14
Build Nginx: 
$ make install

Two modules added to nginx are ngx_devel_kit and lua-nginx-module. lua-resty-redis does not have to be added ./configure script arguments as it is not an Nginx C module, it is a pure Lua library that can be directly required from within your Lua code in the nginx.conf file.

V. Starting Redis as a service

$ sudo systemctl restart redis.service #run redis service
$ sudo systemctl status redis #check the redis service status, which should be active now 
$ ./redis-cli
 redis> set foo apache.org
 OK
 redis> set bar nginx.org
 OK

Check out more information about Redis setup here. Follow the link to configure Nginx server to add virtual host details for dynamic routing.

NOTE:
Add lua_package_path to nginx.conf to find lua-resty-redis module.

lua_package_path “/home/<user>/nginx/lua-resty-redis-0.29/lib/?.lua;;”;

VI. Running Nginx as a service

- Starting Nginx as a service
$ sudo systemctl start nginx
- Checking nginx status which should be active now 
$ sudo systemctl status nginx 
- Testing nginx.conf file. In case of any error, check error.log file to description
$ nginx -t
- Restarting nginx without downtime, reload fails if any error and nginx doesn’t have to stop
$ sudo systemctl reload nginx
- Restarting nginx, can cause a downtime if any error
$ sudo systemctl restart nginx

VII. Testing dynamic routing with curl

- Takes you to nginx server home page
$ curl — user-agent bar localhost
- Takes you to apache.org home page
$ curl --user-agent foo localhost

You can find the reference for nginx.conf file here.