OpenResty is fully compatible with standard NGINX configuration syntax, so most native NGINX directives can be reused, but replacing a production instance directly still carries risk. The two builds can differ in compiled modules, NGINX core versions, default paths, and runtime setup, and dynamic modules built for the original NGINX must be rebuilt for OpenResty. Migrate in four steps: inventory the build with nginx -V and nginx -T, check modules and paths, run both instances in parallel and compare responses, then shift traffic gradually with a rollback plan.

For a comparison of the two platforms before migrating, see OpenResty vs. NGINX: When the Gateway Starts Running Business Logic.

How to migrate from NGINX to OpenResty: align first, then extend

OpenResty is built on the NGINX core, so most native NGINX directives can be reused. But syntax compatibility does not mean a configuration can always be copied over and work as-is. Build options, module lists, and default installation paths often differ, so a direct replacement can cause compatibility problems.

The safest strategy is to separate replacing the gateway runtime from adding new features. First migrate the existing configuration unchanged. Run NGINX and OpenResty in parallel and compare them with the same requests to confirm identical proxy behavior. Once this is stable, introduce new Lua business logic gradually, such as Lua-based API authentication. If something goes wrong, it is easier to determine whether the cause is the base environment or the new Lua code.

The work can be done in four steps. If you do not have an installation yet, start with Installing OpenResty.

Inventory the existing NGINX build and configuration

Before migration, audit and back up the current production environment:

  1. Check the version and build options: Find the NGINX binary actually running in production and run nginx -V. Record the version and complete configure arguments.
  2. Export the full configuration: Run nginx -T, including the exact -p, -c, or -g command-line arguments used by the production service. In addition to checking syntax, -T prints the main configuration and every file loaded through include, making it useful for mapping dependencies.
  3. Back up and record: Back up the original configuration files and directory structure, and record the system user and startup command for the service.

Check modules, directives, and file paths

After making an inventory, check the areas most likely to cause compatibility problems:

  • Built-in modules and core-version differences: Compare the output of nginx -V and openresty -V. If configuration testing reports unknown directive, check whether the original NGINX enabled a non-default module such as http_sub_module. Also check the NGINX core versions. If the current environment uses a newer NGINX Mainline directive, confirm that the core version used by the target OpenResty includes it.
  • Third-party C modules (a common source of errors): Inspect every load_module in the configuration, including ngx_brotli, OpenTelemetry, and internal modules written in C. A .so file built for the original NGINX cannot be used directly with OpenResty. Even when both builds enable NGINX’s --with-compat option, startup still strictly checks the NGINX version and build signature. A version mismatch produces module "…" version … instead of …, and an incompatible build signature produces module "…" is not binary compatible. Either error prevents startup. Rebuild dynamic C modules for the target OpenResty version. If a business module was statically compiled into the old NGINX, consider whether it can be replaced with OpenResty’s Lua ecosystem.
  • Paths and permissions: Check include, TLS certificates, logs, PID files, and temporary directories. Absolute paths are generally fine, but relative paths are resolved against the startup -p prefix. The default working directory changes when switching to OpenResty, so relative paths may stop resolving. Also verify that the new service user, such as nobody or nginx, has the required read and write permissions.

Run both instances and compare the same requests

Passing a -t syntax check only means the configuration can start; it does not prove that proxy behavior is identical. The safest approach in a test environment is to use -p to give NGINX and OpenResty separate working directories, listen on different ports, and compare their responses to the same requests.

The following minimal local experiment assumes nginx, openresty, and python3 are installed. NGINX listens on 18080, OpenResty on 18082, and both forward /api/ to an upstream service on 18081.

Create temporary directories and start a mock upstream with Python:

check_dir=$(mktemp -d)
mkdir -p "$check_dir/conf" "$check_dir/logs" "$check_dir/upstream/api"
printf 'upstream ok\n' > "$check_dir/upstream/api/ping"
python3 -m http.server 18081 --bind 127.0.0.1 --directory "$check_dir/upstream" &
upstream_pid=$!

Run curl -fsS http://127.0.0.1:18081/api/ping and confirm it returns upstream ok.

Save the configuration to $check_dir/conf/nginx.conf. The forwarded headers are included so they can be checked too:

pid logs/nginx.pid;
error_log logs/error.log;

events {}

http {
    access_log logs/access.log;

    server {
        listen 127.0.0.1:18082;
        server_name gateway.test;

        location /api/ {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://127.0.0.1:18081;
        }
    }
}

Copy the same configuration for NGINX, changing only the listen port to 18080. Give both instances their own working directories with -p, test the configurations, and start them:

baseline_dir=$(mktemp -d)
mkdir -p "$baseline_dir/conf" "$baseline_dir/logs"
sed 's/127\.0\.0\.1:18082/127.0.0.1:18080/' "$check_dir/conf/nginx.conf" \
    > "$baseline_dir/conf/nginx.conf"

nginx -p "$baseline_dir/" -c conf/nginx.conf -t &&
    nginx -p "$baseline_dir/" -c conf/nginx.conf
openresty -p "$check_dir/" -c conf/nginx.conf -t &&
    openresty -p "$check_dir/" -c conf/nginx.conf

Send the same request to both ports and compare the proxy results. Bash and Zsh can use diff -u <(curl ...) <(curl ...) to compare output:

curl -isS -H 'Host: gateway.test' http://127.0.0.1:18080/api/ping
curl -isS -H 'Host: gateway.test' http://127.0.0.1:18082/api/ping

Both should return 200 and upstream ok. A request for a missing path such as /api/missing should return 404 from both. Differences in headers such as Server and Date are normal. Focus on status codes, response bodies, and application-specific response headers that clients depend on.

For a real migration, replay representative requests for core routes, including both normal and expected error cases. Compare error logs, the headers received by the upstream, access logs, and TLS handshakes.

When the local experiment is complete, stop both temporary instances and the test upstream:

openresty -p "$check_dir/" -c conf/nginx.conf -s quit
nginx -p "$baseline_dir/" -c conf/nginx.conf -s quit
kill "$upstream_pid"

Shift traffic gradually and prepare rollback

After validation in the test environment, prepare to switch production traffic.

If a load balancer sits in front of the gateway, keep the NGINX instance running and first send a small share of canary traffic to OpenResty. Before switching, agree on the observation period and the thresholds for increasing traffic or triggering rollback, especially error rate and latency. Monitor both instances and upstream services during the canary. Increase the share gradually when the results meet expectations. If a threshold is crossed, send traffic back to NGINX immediately and repeat key requests to confirm recovery.

Two rollback details are easy to miss:

  1. Align security policies: If new security or authentication logic is introduced during migration, such as blocking a class of invalid requests, ensure the original NGINX has a fallback policy too. Otherwise a rollback could remove that protection.
  2. Handle port conflicts: Without a load balancer, if both services must bind to port 80/443 on the same host one at a time, a gradual canary is not possible. Prepare a one-click rollback script in advance: stop OpenResty, start the original NGINX, and send a test request. This should restore service within seconds if something goes wrong.

Summary and next steps

The key to migrating from NGINX to OpenResty is not replacing everything at once, but splitting up the risk: migrate the existing configuration as-is, confirm that proxy behavior matches, and then add Lua business logic gradually.

Use four steps: inspect the current build and configuration with nginx -V and nginx -T; check modules, core versions, dynamic modules, and paths; run both instances in parallel in a test environment and compare status codes, response bodies, and application-specific response headers; then shift traffic gradually with clear rollback thresholds and steps. If an issue appears after launch, this makes it easier to determine whether it comes from the base configuration or newly added Lua code and to return to NGINX promptly.

This article is part of the OpenResty tutorial series. After migrating, see OpenResty Components to learn which modules and Lua libraries can extend your existing proxy configuration.

If you like this tutorial series, subscribe to this blog and our YouTube channel.

About The Author

Yichun Zhang (GitHub handle: agentzh), is the original creator of the OpenResty® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.