nginx-build

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

Requirements

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

Build Support

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

Installation

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

Quick Start

nginx-build -d work

Custom Configuration

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

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

Embedding zlib statically

Give -zlib to nginx-build.

$ nginx-build -d work -zlib

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

Embedding PCRE statically

Give -pcre to nginx-build.

$ nginx-build -d work -pcre

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

Embedding OpenSSL statically

Give -openssl to nginx-build.

$ nginx-build -d work -openssl

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

Embedding LibreSSL statically

Give -libressl to nginx-build.

$ nginx-build -d work -libressl

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

Using a Custom nginx Source

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.

Basic Usage

# 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

Using a Specific Git Tag or Branch

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

Available Options

• -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.

Using Custom SSL Libraries (e.g., BoringSSL)

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.

Basic Usage

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

Using a Specific Git Tag or Branch

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

Using a Tarball URL

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.

Available Options

• -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)

Supported Git Repository Formats

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.

Embedding 3rd-party modules

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

Embedding 3rd-party module dynamically

Give true to dynamic.

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

Provision for 3rd-party module

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": ".."
  }
]

Applying patch before building nginx

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"

Idempotent build

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.

Build OpenResty

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.

Build Custom nginx Sources

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.

Build Angie

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.

Build freenginx

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.