# nginx-binaries

**Repository Path**: zenaster/nginx-binaries

## Basic Information

- **Project Name**: nginx-binaries
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-01-01
- **Last Updated**: 2024-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= 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 <<Files Repository>>).
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 <<IndexEntry>> 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 (EOL) +
1.24.x (stable) +
1.25.x (mainline)

.3+| _default_
| Linux
| x86_64 +
aarch64 +
ppc64le +
pass:[<s>armv7</s>] 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:[<s>armv7</s>] 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@1.1, 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 1.1.x, pcre 8.x and zlib 1.2.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, openssl@1.1, ncurses, pcre and zlib from https://brew.sh[Homebrew].

endif::npm-readme[]