Architecture

The repository is organized as a deterministic packaging pipeline. Its boundary is the generated Debian package; runtime behavior happens after that package is installed on a Debian host.

Build flow

scripts/fetch-sources.sh
  -> build/cache and build/src
scripts/build.sh
  -> build/stage with compiled libmodsecurity and OpenResty
scripts/package.sh
  -> build/stage enriched with config, systemd, CRS, logrotate, sysctl
  -> build/dist/*.deb and *.sha256
scripts/smoketest.sh
  -> clean Debian container install and HTTP verification

Source resolution

scripts/fetch-sources.sh resolves OpenResty from the official download page and GitHub-hosted modules from releases, tags, or default branches. The effective source versions are recorded in build/sources.manifest so the package metadata and release artifacts can report exactly what was built.

Key upstreams include:

Component	Source
OpenResty	openresty.org stable download page
ModSecurity	owasp-modsecurity/ModSecurity
ModSecurity-nginx	owasp-modsecurity/ModSecurity-nginx
GeoIP2 module	leev/ngx_http_geoip2_module
AJP module	msva/nginx_ajp_module default branch
Brotli	google/ngx_brotli default branch
OWASP CRS	coreruleset/coreruleset

Compile stage

scripts/build.sh first builds libmodsecurity with Lua, LMDB, PCRE2, GeoIP, and parser generation support. It then configures OpenResty with Debian-friendly hardening flags, OpenResty/nginx paths, HTTP/2 and HTTP/3 support, dynamic modules, and the additional modules from the fetched sources.

OpenResty is installed into build/stage via DESTDIR. That stage tree becomes the root filesystem image for the .deb.

Package stage

scripts/package.sh copies repository configuration and operational files into the stage tree, including:

• /etc/nginx templates and default site activation.
• /etc/modsecurity configuration and OWASP CRS.
• openresty.service and tmpfiles definitions.
• logrotate, sysctl, profile, and /usr/local/sbin/openresty symlink.
• Debian control metadata and maintainer scripts.

The package version is OPENRESTY_VERSION-PKG_REVISION~deb13, which keeps Debian version ordering predictable for upgrades.

Runtime architecture

At runtime, openresty.service owns the service lifecycle. It validates configuration before start, reloads through the OpenResty binary, and applies systemd hardening such as PrivateTmp, ProtectSystem=full, NoNewPrivileges, and a restricted capability set for binding low ports.