Using the Lua SDK with NGINX

This guide explains how to use our Lua server-side SDK with the NGINX OpenResty framework.

OpenResty extends NGINX with LuaJIT, enabling complex control of NGINX functionality. The OpenResty framework has substantial commercial adoption.

Find a basic Dockerized app in the GitHub repository at hello-nginx.

Prerequisites

To complete this guide, you must have the following prerequisites:

• Basic working knowledge of the LaunchDarkly Lua server-side SDK
• Basic working knowledge of the LaunchDarkly C++ server-side SDK

The C++ server-side SDK is required because the Lua server-side SDK is implemented as a wrapper around the C++ server-side SDK.

Preparing the Lua server-side SDK

Make the source of the Lua SDK accessible to OpenRESTY. You can control imports with the lua_package_path directive.

For example:

1
http {
2
    lua_package_path ";;/usr/local/openresty/nginx/scripts/?.lua;";
3
    ...
4
}

Preparing the C++ server-side SDK

Make the source of the C++ server-side SDK accessible to the dynamic linker. The most convenient way to do this is to install the binary system-wide at /usr/lib/libldserverapi.so.

Ensuring correct initialization

The most important part of effective SDK usage is managing the lifetime of clients correctly. Because NGINX utilizes process-based concurrency, multiple clients initiate. If you accidentally initiate a client per request the application will be substantially slower, as the SDK has to download a fresh ruleset from LaunchDarkly.

Initialize each NGINX worker process exactly once for ideal operations. You can do this with the init_worker_by_lua_file directive. This directive executes a script when a process is freshly spawned. Client initialization should reside in this script. In the example below, this file is called shared.lua.

Here is an example of initialization logic:

1
local ld = require("launchdarkly_server_sdk")
2
local os = require("os")
3
4
return ld.clientInit(os.getenv(sdk_key), 1000, config)

Later we can use the result of this initialization process in other directives.

1
local ld     = require("launchdarkly_server_sdk")
2
local client = require("shared")
3
local os     = require("os")
4
5
local context = ld.makeContext({
6
    user = {
7
      key = "abc"
8
    }
9
})
10
11
if client:boolVariation(context, "example-flag-key", false) then
12
    ngx.say("<p>feature launched</p>")
13
else
14
    ngx.say("<p>feature not launched</p>")
15
end

Example: Feature flagged reverse proxy

This reverse proxy example demonstrates more complex interaction between multiple NGINX directives. You can use a reverse proxy to route traffic to multiple applications.

The example follows:

1
location / {
2
    set $proxy_host "";
3
4
    rewrite_by_lua_block {
5
        local ld     = require("launchdarkly_server_sdk")
6
        local client = require("shared")
7
8
        local context = ld.makeContext({
9
            user = {
10
              key = "abc"
11
            }
12
        })
13
14
        ngx.var.proxy_host = client:stringVariation(context, "example-flag-key", "10.0.0.0")
15
    }
16
17
    proxy_pass                       https://$proxy_host$uri;
18
    proxy_set_header Host            $proxy_host;
19
    proxy_set_header X-Forwarded-For $remote_addr;
20
}