nginx-binaries
Nginx and njs binaries for Linux (x86_64, aarch64, ppc64le), macOS and Windows. Linux binaries are static so works on every Linux.
= nginx and njs standalone binaries :toc: macro :toc-title: // custom :npm-name: nginx-binaries :gh-name: jirutka/{npm-name} :alpine-branch: 3.18 :nginx-docs-uri: http://nginx.org/en/docs/
ifdef::env-github[] image:https://github.com/{gh-name}/workflows/binaries/badge.svg[Binaries Workflow, link=https://github.com/{gh-name}/actions?query=workflow%3A%22binaries%22] endif::env-github[]
This project provides standalone nginx and njs (NGINX JavaScript) binaries for any Linux system footnote:[nginx binaries are built as standalone static executables, so they works on every Linux system regardless of used libc.] (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).
ifndef::npm-readme[]
You can also download the binaries manually from https://jirutka.github.io/nginx-binaries/ or https://github.com/{gh-name}/tree/binaries[binaries] branch (see <>). They are built automatically and periodically using GitHub Actions (see link:.github/workflows/binaries.yml[config]).
== Table of Contents
toc::[]
== JS Library
ifdef::env-github[] image:https://github.com/{gh-name}/workflows/js/badge.svg[JS Workflow, link=https://github.com/{gh-name}/actions?query=workflow%3A%22js%22] image:https://img.shields.io/npm/v/{npm-name}.svg[npm Version, link="https://www.npmjs.org/package/{npm-name}"] image:https://badgen.net/bundlephobia/dependency-count/{npm-name}[Dependency Count, link="https://bundlephobia.com/result?p={npm-name}"] endif::env-github[]
endif::npm-readme[]
=== Installation
[source, sh, subs="+attributes"]
using npm:
npm install --save-dev {npm-name}
or using yarn:
yarn add --dev {npm-name}
=== Usage Example
[source, js, subs="+attributes"]
import { NginxBinary, NjsBinary } from '{npm-name}'
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
// Pandoc conversion to Markdown doesn't handle definition lists. ifdef::npm-readme[] https://github.com/{gh-name}#api[See on GitHub].
endif::npm-readme[] ifndef::npm-readme[]
==== 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 https://github.com/npm/node-semver#ranges[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:
[source, js]
{
'openssl': '1.1.1i-r0',
'echo-nginx-module': '0.62',
}
=== Logging
. If https://github.com/Download/anylogger[anylogger] is available and initialized (any adapter has been registered), then:
** all log messages will go through anylogger logger nginx-binaries.
. If https://www.npmjs.com/package/debug[debug] is available, then:
** debug messages will be logged via debug logger nginx-binaries, others (error, warn, info) via console.
. 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):
[source, js, subs="+attributes"]
import { setLogger } from '{npm-name}'
setLogger({
warn: console.warn,
error: console.error,
// undefined logging functions will be replaced with no-op
})
== Files Repository
The built binaries are stored in https://github.com/{gh-name}/tree/binaries[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 <> for description of <name>, <version> etc.
Suffix .exe is used for Windows binaries only.
== Binaries
[cols=5] |=== | Program | Version Range(s) | Variant(s) | OS | Architecture(s)
.3+| nginx .3+| 1.18.x (EOL) + 1.19.x (EOL) footnote:[The first available nginx version in branch 1.19.x is 1.19.5.] + 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)
.3+| default | Linux | x86_64 + aarch64 + ppc64le + pass:[armv7] footnote:armv7[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.]
| macOS | x86_64
| Windows | x86_64 (x64)
.3+| njs .2+| 0.x.x footnote:[The first available njs version is 0.5.0.] .2+| default + debug | Linux | x86_64 + aarch64 + ppc64le + pass:[armv7] footnote:armv7[]
| macOS | x86_64 |===
=== nginx
Linux binary is statically linked with https://www.musl-libc.org[musl libc], jansson, openssl (3.x), pcre and zlib from https://alpinelinux.org[Alpine Linux] {alpine-branch}. It’s compiled with debug mode, threads and aio.
macOS binary is statically linked with jansson, openssl@3, pcre and zlib from https://brew.sh[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 https://github.com/myfreeer/nginx-build-msys2[nginx-build-msys2] made by https://github.com/myfreeer[@myfreeer].
==== Included Modules
Built-In Modules:
- {nginx-docs-uri}/http/ngx_http_access_module.html[ngx_http_access_module]
- {nginx-docs-uri}/http/ngx_http_auth_basic_module.html[ngx_http_auth_basic_module]
- {nginx-docs-uri}/http/ngx_http_auth_request_module.html[ngx_http_auth_request_module]
- {nginx-docs-uri}/http/ngx_http_autoindex_module.html[ngx_http_autoindex_module]
- {nginx-docs-uri}/http/ngx_http_browser_module.html[ngx_http_browser_module]
- {nginx-docs-uri}/http/ngx_http_charset_module.html[ngx_http_charset_module]
- {nginx-docs-uri}/http/ngx_http_empty_gif_module.html[ngx_http_empty_gif_module]
- {nginx-docs-uri}/http/ngx_http_gzip_module.html[ngx_http_gzip_module]
- {nginx-docs-uri}/http/ngx_http_limit_conn_module.html[ngx_http_limit_conn_module]
- {nginx-docs-uri}/http/ngx_http_limit_req_module.html[ngx_http_limit_req_module]
- {nginx-docs-uri}/http/ngx_http_map_module.html[ngx_http_map_module]
- {nginx-docs-uri}/http/ngx_http_proxy_module.html[ngx_http_proxy_module]
- {nginx-docs-uri}/http/ngx_http_realip_module.html[ngx_http_realip_module]
- {nginx-docs-uri}/http/ngx_http_referer_module.html[ngx_http_referer_module]
- {nginx-docs-uri}/http/ngx_http_rewrite_module.html[ngx_http_rewrite_module]
- {nginx-docs-uri}/http/ngx_http_secure_link_module.html[ngx_http_secure_link_module]
- {nginx-docs-uri}/http/ngx_http_ssl_module.html[ngx_http_ssl_module]
- {nginx-docs-uri}/http/ngx_http_upstream_hash_module.html[ngx_http_upstream_hash_module]
- {nginx-docs-uri}/http/ngx_http_upstream_ip_hash_module.html[ngx_http_upstream_ip_hash_module]
- {nginx-docs-uri}/http/ngx_http_upstream_keepalive_module.html[ngx_http_upstream_keepalive_module]
- {nginx-docs-uri}/http/ngx_http_upstream_least_conn_module.html[ngx_http_upstream_least_conn_module]
- {nginx-docs-uri}/http/ngx_http_upstream_random_module.html[ngx_http_upstream_random_module]
- {nginx-docs-uri}/http/ngx_http_upstream_zone_module.html[ngx_http_upstream_zone_module]
- {nginx-docs-uri}/http/ngx_http_userid_module.html[ngx_http_userid_module]
- {nginx-docs-uri}/http/ngx_http_v2_module.html[ngx_http_v2_module]
Extra Modules: footnote:[Modules that are provided by NGINX but released separately.]
- {nginx-docs-uri}/http/ngx_http_js_module.html[ngx_http_js_module] (except Windows footnote:[njs is not supported on Windows, see https://github.com/nginx/njs/issues/320[nginx/njs#320]])
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:
- https://github.com/openresty/echo-nginx-module[echo-nginx-module]
- https://github.com/openresty/headers-more-nginx-module[headers-more-nginx-module]
- https://github.com/vision5/ngx_devel_kit[ngx_devel_kit]
- https://github.com/openresty/set-misc-nginx-module[set-misc-nginx-module]
- https://github.com/kjdev/nginx-auth-jwt[kjdev/nginx-auth-jwt] (since 1.22.1, 1.23.4, and 1.24.0; except Windows binaries)
- https://github.com/kjdev/nginx-keyval[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 https://www.musl-libc.org[musl libc], libedit, openssl (3.x), ncurses, pcre and zlib from https://alpinelinux.org[Alpine Linux] {alpine-branch}.
macOS binary is statically linked with libedit, [email protected], ncurses, pcre and zlib from https://brew.sh[Homebrew].
endif::npm-readme[]