README.adoc

nginx and njs standalone binaries

This project provides standalone nginx and njs (NGINX JavaScript) binaries for any Linux system ^[1] (x86_64, aarch64, ppc64le), macOS (x86_64), and Windows (x86_64). It also provides a JS library for downloading these binaries (for use in integration tests).

You can also download the binaries manually from https://jirutka.github.io/nginx-binaries/ or binaries branch (see Files Repository). They are built automatically and periodically using GitHub Actions (see config).

Table of Contents

• Table of Contents
• JS Library
  • Installation
  • Usage Example
  • API
  • Logging
• Files Repository
• Binaries
  • nginx
  • njs

JS Library

Installation

# using npm:
npm install --save-dev nginx-binaries
# or using yarn:
yarn add --dev nginx-binaries

Usage Example

import { NginxBinary, NjsBinary } from 'nginx-binaries'

await NginxBinary.versions({ version: '^1.21.5' })
// => ['1.21.5', '1.21.6', '1.22.0']

await NginxBinary.download({ version: '1.22.x' })
// => '[...]/node_modules/.cache/nginx-binaries/nginx-1.22.0-x86_64-linux'

await NjsBinary.versions({ version: '^0.7.0' })
// => ['0.7.1', '0.7.2', '0.7.3', '0.7.4']

await NjsBinary.download({ version: '^0.7.0', variant: 'debug' }, '.tmp/njs')
// => '.tmp/njs'

API

NginxBinary / NjsBinary

cacheDir (string)

Path to the cache directory where the repository index and binaries are stored.

Defaults to .cache/nginx-binaries/ relative to the nearest writable node_modules (nearest to process.cwd()) or nginx-binaries/ in the system-preferred temp directory.

cacheMaxAge (number)

Maximum age in minutes for the cached repository index in cacheDir to be considered fresh. If the cached index is stale, the Downloader tries to refresh it before reading.

Defaults to 480 (8 hours).

repoUrl (string)

URL of the repository with binaries.

Caution: After changing repoUrl, you should delete old index.json in cacheDir or disable index cache by setting cacheMaxAge to 0.

Defaults to 'https://jirutka.github.io/nginx-binaries'.

timeout (number)

Fetch response timeout in milliseconds.

Defaults to 10000 (10 seconds).

download (query: Query, destFilePath?: string) ⇒ Promise<string>

Downloads a binary specified by query and stores it in the cacheDir or in destFilePath, if provided. Returns path to the file.

If the file already exists and the checksums match, it just returns its path.

If multiple versions satisfies the version range, the one with highest version number is selected.

search (query: Query) ⇒ Promise<IndexEntry[]>

Returns metadata of available binaries that match the query.

variants (query?: Query) ⇒ Promise<string[]>

Returns all the available variants matching the query.

versions (query?: Query) ⇒ Promise<string[]>

Returns all the available versions matching the query.

Query

version (?string)

Specify required version as exact version number or a SemVer version range.

Example: '1.8.0', '1.8.x', '^1.8.0'

variant (?string)

Specify build variant of the binary (e.g. debug). Defaults to an empty string, i.e. the default variant.

os (?string)

Specify target OS. Defaults to the host OS.

arch (?string)

Specify target CPU architecture. Defaults to the host architecture.

IndexEntry

name (string)

Name of the program: 'nginx' or 'njs'.

version (string)

Version of the program.

variant (string)

The build variant of the binary (e.g. debug). An empty string indicates the default variant.

os (string)

OS platform for which this binary was built: 'darwin' (macOS), 'linux' (Linux), or 'win32' (Windows).

arch (string)

CPU architecture for which this binary was built: 'armv7', 'aarch64', 'ppc64le', or 'x86_64'.

filename (string)

Full name of the binary file.

date (string)

Date and time (ISO-8601) at which the binary was built.

size (number)

Size of the binary file in bytes.

checksum (string)

Checksum of the binary file in format <algorithm>:<hash>.

Example: 'sha1:7336b675b26bd67fdda3db18c66fa7f64691e280'

bundledLibs (Object.<string, string>)

A record of all libraries (or modules) statically linked into the binary and the version number.

Example:

{
  'openssl': '1.1.1i-r0',
  'echo-nginx-module': '0.62',
}

Logging

1. If anylogger is available and initialized (any adapter has been registered), then:

   • all log messages will go through anylogger logger nginx-binaries.

2. If debug is available, then:

   • debug messages will be logged via debug logger nginx-binaries, others (error, warn, info) via console.

3. otherwise:

   • error, warn, and info messages will be logged via console, debug messages will be discarded.

If none of these options is suitable, you can provide your own logger using setLogger(object):

import { setLogger } from 'nginx-binaries'

setLogger({
  warn: console.warn,
  error: console.error,
  // undefined logging functions will be replaced with no-op
})

Files Repository

The built binaries are stored in binaries branch of this git repository which is published on https://jirutka.github.io/nginx-binaries/.

The repository contains the following types of files:

• index.{csv,json,html} — Repository index in CSV, JSON and HTML formats.

• <name>-<version>[-<variant>]-<arch>-<os>[.exe] — Program binary for particular architecture and OS.

• <name>-<version>[-<variant>]-<arch>-<os>[.exe].sha1 — SHA-1 checksum of the binary file.

• <name>-<version>[-<variant>]-<arch>-<os>[.exe].sources — List of all source tarballs and system-provided static libraries from which the binary was built.

See IndexEntry for description of <name>, <version> etc. Suffix .exe is used for Windows binaries only.

Binaries

Program	Version Range(s)	Variant(s)	OS	Architecture(s)
nginx	1.18.x (EOL) 1.19.x (EOL) [2] 1.20.x (EOL) 1.21.x (EOL) 1.22.x (EOL) 1.23.x (EOL) 1.24.x (old stable) 1.25.x (mainline) 1.26.x (stable)	default	Linux	x86_64 aarch64 ppc64le armv7 [3]
			macOS	x86_64
			Windows	x86_64 (x64)
njs	0.x.x [4]	default debug	Linux	x86_64 aarch64 ppc64le armv7 [3]
			macOS	x86_64

nginx

Linux binary is statically linked with musl libc, jansson, openssl (3.x), pcre and zlib from Alpine Linux 3.18. It’s compiled with debug mode, threads and aio.

macOS binary is statically linked with jansson, openssl@3, pcre and zlib from Homebrew. It’s compiled with debug mode, threads and aio.

Windows binary is statically linked with latest openssl 3.3.x, pcre 8.x and zlib 1.3.x built from sources. It’s compiled with debug mode and patches from nginx-build-msys2 made by @myfreeer.

Included Modules

Built-In Modules:

• ngx_http_access_module

• ngx_http_auth_basic_module

• ngx_http_auth_request_module

• ngx_http_autoindex_module

• ngx_http_browser_module

• ngx_http_charset_module

• ngx_http_empty_gif_module

• ngx_http_gzip_module

• ngx_http_limit_conn_module

• ngx_http_limit_req_module

• ngx_http_map_module

• ngx_http_proxy_module

• ngx_http_realip_module

• ngx_http_referer_module

• ngx_http_rewrite_module

• ngx_http_secure_link_module

• ngx_http_ssl_module

• ngx_http_upstream_hash_module

• ngx_http_upstream_ip_hash_module

• ngx_http_upstream_keepalive_module

• ngx_http_upstream_least_conn_module

• ngx_http_upstream_random_module

• ngx_http_upstream_zone_module

• ngx_http_userid_module

• ngx_http_v2_module

Extra Modules: ^[5]

• ngx_http_js_module (except Windows ^[6])

Since nginx 1.22.0, the stable and mainline versions of nginx include the latest version of njs available at the time of building. The old stable versions of nginx include the latest minor (i.e. x.Y.z) version of njs released prior to the release of a new stable nginx (and the latest patch version available at the time of building). That is, it’s the same as in NGINX’s own packages.

3rd Party Modules:

• echo-nginx-module

• headers-more-nginx-module

• ngx_devel_kit

• set-misc-nginx-module

• kjdev/nginx-auth-jwt (since 1.22.1, 1.23.4, and 1.24.0; except Windows binaries)

• nginx-keyval (since 1.22.1, 1.23.4, and 1.24.0; except Windows binaries)

nginx binaries include the latest version of the third-party modules available at the time of building.

njs

Linux binary is statically linked with musl libc, libedit, openssl (3.x), ncurses, pcre and zlib from Alpine Linux 3.18.

macOS binary is statically linked with libedit, [email protected], ncurses, pcre and zlib from Homebrew.

---

1. nginx binaries are built as standalone static executables, so they works on every Linux system regardless of used libc.

2. The first available nginx version in branch 1.19.x is 1.19.5.

3. As of January 2023, binaries for armv7 are no longer built — gcc runs out of memory when building njs using the QEMU emulator. If you want support for armv7, let me know in issues.

4. The first available njs version is 0.5.0.

5. Modules that are provided by NGINX but released separately.

6. njs is not supported on Windows, see nginx/njs#320