nginx-build - provides a command to build nginx seamlessly.

• git and hg for downloading 3rd party modules
• patch for applying patch to nginx

• nginx
• OpenResty
• freenginx
• Custom nginx sources via -customnginx (for example Angie, nginx forks, and feature branches)

go install github.com/cubicdaiya/nginx-build@latest

nginx-build -d work

nginx-build provides a mechanism for customizing configuration for building nginx.

Prepare a configure script like the following.

#!/bin/sh

./configure \
--sbin-path=/usr/sbin/nginx \
--conf-path=/etc/nginx/nginx.conf \

Give this file to nginx-build with -c.

$ nginx-build -d work -c configure.example

Give -zlib to nginx-build.

$ nginx-build -d work -zlib

-zlibversion is an option to set a version of zlib.

Give -pcre to nginx-build.

$ nginx-build -d work -pcre

-pcreversion is an option to set a version of PCRE.

Give -openssl to nginx-build.

$ nginx-build -d work -openssl

-opensslversion is an option to set a version of OpenSSL.

Give -libressl to nginx-build.

$ nginx-build -d work -libressl

-libresslversion is an option to set a version of LibreSSL.

nginx-build can also build nginx from a custom URL, in the same way as -customssl. The URL can be either a tarball or a Git repository.

This is intended for custom nginx trees in general, such as Angie, nginx forks, QUIC branches, or internal vendor branches.

# Using Angie from Git repository
$ nginx-build -d work \
  -customnginx https://github.com/webserver-llc/angie.git \
  -customnginxname angie

# Using a tarball URL
$ nginx-build -d work \
  -customnginx https://example.com/nginx-quic.tar.gz \
  -customnginxname nginx-quic

# Using a custom nginx branch from Git
$ nginx-build -d work \
  -customnginx https://github.com/example/nginx.git \
  -customnginxname nginx-feature \
  -customnginxtag feature/http3

For Git repositories, you can specify a tag or branch with -customnginxtag:

# Use Angie with a specific tag
$ nginx-build -d work \
  -customnginx https://github.com/webserver-llc/angie.git \
  -customnginxname angie \
  -customnginxtag Angie-1.11.3

# Use another custom nginx tree with a specific tag
$ nginx-build -d work \
  -customnginx https://github.com/example/nginx-quic.git \
  -customnginxname nginx-quic \
  -customnginxtag v1.0.0

• -customnginx: URL of the custom nginx source (supports both Git repositories and tarballs)
• -customnginxname: Name for the custom nginx source (used in directory names)
• -customnginxtag: Git tag or branch to checkout (only for Git repositories)

For tarball URLs, the archive must extract into a single top-level directory. Archives that unpack files directly at the root, or contain multiple top-level directories, are not supported.

nginx-build supports using arbitrary SSL libraries through custom SSL options. This is useful for libraries like BoringSSL that are not available as standard options.

To use a custom SSL library, provide the download URL with -customssl. The URL can be either a tarball or a Git repository:

# Using BoringSSL from Git repository
$ nginx-build -d work -customssl https://boringssl.googlesource.com/boringssl -customsslname boringssl

# Using a tarball URL
$ nginx-build -d work -customssl https://example.com/customssl-1.0.0.tar.gz -customsslname customssl

For Git repositories, you can specify a tag or branch with -customssltag:

# Use BoringSSL with chromium-stable branch
$ nginx-build -d work \
  -customssl https://boringssl.googlesource.com/boringssl \
  -customsslname boringssl \
  -customssltag chromium-stable

# Use OpenSSL from Git with specific tag
$ nginx-build -d work \
  -customssl https://github.com/openssl/openssl.git \
  -customsslname openssl-git \
  -customssltag openssl-3.5.1

# Use oqs-provider (OpenSSL provider) with tag 0.9.0
$ nginx-build -d work \
  -customssl https://github.com/open-quantum-safe/oqs-provider.git \
  -customsslname oqs-provider \
  -customssltag 0.9.0

You can also use tarball URLs for custom SSL libraries:

# Using a custom OpenSSL build from a tarball
$ nginx-build -d work \
  -customssl https://example.com/myssl-1.0.0.tar.gz \
  -customsslname myssl

The tarball must extract into a single top-level directory. Archives that unpack files directly at the root, or contain multiple top-level directories, are not supported.

• -customssl: URL of the custom SSL library (supports both Git repositories and tarballs)
• -customsslname: Name for the custom SSL library (used in directory names)
• -customssltag: Git tag or branch to checkout (only for Git repositories)

The following Git repository URL formats are automatically detected:

• URLs ending with .git
• URLs using git:// protocol
• GitHub repository URLs (e.g., https://github.com/user/repo)
• Google Source URLs (e.g., https://boringssl.googlesource.com/boringssl)

Note: URLs containing /releases/download/ or /archive/ are treated as tarball downloads, not Git repositories.

nginx-build provides a mechanism for embedding 3rd-party modules. Prepare a json file below.

[
  {
    "name": "ngx_http_hello_world",
    "form": "git",
    "url": "https://github.com/cubicdaiya/ngx_http_hello_world"
  }
]

Give this file to nginx-build with -m.

$ nginx-build -d work -m modules.json.example

Give true to dynamic.

[
  {
    "name": "ngx_http_hello_world",
    "form": "git",
    "url": "https://github.com/cubicdaiya/ngx_http_hello_world",
    "dynamic": true
  }
]

There are some 3rd-party modules expected provision. nginx-build provides the options such as shprov and shprovdir for this problem. There is the example configuration below.

[
  {
    "name": "njs/nginx",
    "form": "hg",
    "url": "https://hg.nginx.org/njs",
    "shprov": "./configure && make",
    "shprovdir": ".."
  }
]

nginx-build provides the options such as -patch and -patch-opt for applying patches to the extracted sources. By default -patch <path> targets the primary tree (nginx, OpenResty, freenginx, or a custom nginx source depending on the build). To patch other bundled components prefix the flag with the component name, for example -patch openssl=/path/to/openssl.patch. Supported targets include nginx, openresty, freenginx, customnginx (or the custom name), pcre/pcre2, openssl, libressl, customssl (or the custom name), and zlib.

nginx-build \
 -d work \
 -openssl \
 -patch patches/nginx.patch \
 -patch openssl=patches/openssl.patch \
 -patch-opt "-p1"

nginx-build supports a certain level of idempotent build of nginx. If you want to ensure a build of nginx idempotent and do not want to build nginx as same as already installed nginx, give -idempotent to nginx-build.

$ nginx-build -d work -idempotent

-idempotent ensures an idempotent by checking the software versions below.

• nginx
• PCRE
• zlib
• OpenSSL

On the other hand, -idempotent does not cover versions of 3rd party modules and dynamic linked libraries.

nginx-build supports to build OpenResty.

$ nginx-build -d work -openresty -pcre -openssl

If you don't install PCRE and OpenSSL on your system, it is required to add the option -pcre and -openssl.

And there is the limitation for the support of OpenResty. nginx-build does not allow to use OpenResty's unique configure options directly. If you want to use OpenResty's unique configure option, Configuration for building nginx is helpful.

nginx-build supports building custom nginx sources through -customnginx.

$ nginx-build -d work \
  -customnginx https://github.com/example/nginx.git \
  -customnginxname nginx-feature \
  -customnginxtag feature/http3 \
  -pcre \
  -zlib \
  -openssl

If you don't install PCRE, zlib, and OpenSSL on your system, it is required to add -pcre, -zlib, and -openssl. You can use -patch customnginx=/path/to/patch.diff, or -patch <customnginxname>=/path/to/patch.diff when -customnginxname is set.

nginx-build supports building Angie through -customnginx.

$ nginx-build -d work \
  -customnginx https://github.com/webserver-llc/angie.git \
  -customnginxname angie \
  -customnginxtag Angie-1.11.3 \
  -pcre \
  -zlib \
  -openssl

If you don't install PCRE, zlib, and OpenSSL on your system, it is required to add -pcre, -zlib, and -openssl. You can also use -patch angie=/path/to/patch.diff when -customnginxname angie is set.

nginx-build supports to build freenginx.

$ nginx-build -d work -freenginx -openssl

If you don't install OpenSSL on your system, it is required to add the option -openssl.