Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jirutka/nginx-binaries

Nginx and njs binaries for Linux (x86_64, aarch64, ppc64le), macOS and Windows. Linux binaries are static so works on every Linux.
https://github.com/jirutka/nginx-binaries

binaries javascript nginx nginx-linux nginx-macos nginx-windows njs static-binaries

Last synced: 3 months ago
JSON representation

Nginx and njs binaries for Linux (x86_64, aarch64, ppc64le), macOS and Windows. Linux binaries are static so works on every Linux.

Lists

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 <>).

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 (EOL) +

1.24.x (stable) +

1.25.x (mainline)



.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.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, [email protected], ncurses, pcre and zlib from https://brew.sh[Homebrew].



endif::npm-readme[]