= 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: <>, destFilePath?: string) => Promise::
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: <>) => Promise<<>[]>::
Returns metadata of available binaries that match the query.

variants (query?: <>) => Promise::
Returns all the available variants matching the query.

versions (query?: <>) => Promise::
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 :.
+
Example: 'sha1:7336b675b26bd67fdda3db18c66fa7f64691e280'

bundledLibs (Object.)::
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.
* -[-]--[.exe] -- Program binary for particular architecture and OS.
* -[-]--[.exe].sha1 -- SHA-1 checksum of the binary file.
* -[-]--[.exe].sources -- List of all source tarballs and system-provided static libraries from which the binary was built.

See <> for description of , 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 (old stable) +
1.23.x (mainline) +
1.24.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], openssl, 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 openssl, 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, pcre and zlib 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_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]])
* {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]

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]

=== njs

Linux binary is statically linked with https://www.musl-libc.org[musl libc], libedit, ncurses, pcre and zlib from https://alpinelinux.org[Alpine Linux] {alpine-branch}.

macOS binary is statically linked with libedit, ncurses, pcre and zlib from https://brew.sh[Homebrew].

endif::npm-readme[]