= 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 (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[]