Skip to content

Latest commit

 

History

History
193 lines (142 loc) · 5.39 KB

INSTALL.md

File metadata and controls

193 lines (142 loc) · 5.39 KB

Install

This document describes the building process to compile an Nginx release with ngx_wasm_module as an addon.

ngx_wasm_module source releases are available as ngx_wasm_module-*.tar.gz assets at: https://github.com/Kong/ngx_wasm_module/releases.

Note: the wasmx-*.tar.gz releases are pre-compiled, self-contained binaries of Nginx built with this module and as such, do not necessitate any particular installation steps. Download these releases and instantly use the nginx binary.

If you wish however to use other Nginx compilation flags (e.g. add/disable other modules, configure default options, non-default platform/architecture support...) you will then need to compile Nginx yourself following the steps provided below.

Table of Contents

Requirements

Nginx

Ensure that you have all the necessary dependencies to build Nginx on your system. See DEVELOPER.md for a list of platform-specific dependencies.

Download Nginx at https://nginx.org/en/download.html and extract it:

$ tar -xvf nginx-*.tar.gz

Back to TOC

WebAssembly runtime

Several runtimes are supported, and at least one of them must be specified:

  • Wasmtime (see Releases, download and extract the *-c-api.tar.xz asset matching your OS and architecture).
  • Wasmer (see Releases, download and extract the asset matching your architecture).
  • V8 (not pre-built for embedding; but can be compiled locally by this module's build environment: run NGX_WASM_RUNTIME=v8 make setup without having set NGX_WASM_RUNTIME_LIB or NGX_WASM_RUNTIME_INC. See DEVELOPER.md for more details).

Back to TOC

ngx_wasm_module release

Download any of the source code releases at https://github.com/Kong/ngx_wasm_module/releases and extract the archive:

$ tar -xvf ngx_wasm_module-*.tar.gz

Back to TOC

Build

Configure Nginx with ngx_wasm_module and any other flags typically given to your Nginx builds:

$ cd nginx-*
$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --with-cc-opt='-O3 -I/path/to/wasmtime/include' \
    --with-ld-opt='-L/path/to/wasmtime/lib -lwasmtime -Wl,-rpath,/path/to/wasmtime/lib'

Note: to compile with Wasmer, export the NGX_WASM_RUNTIME=wasmer environment variable. See Examples for a list of supported environment variables.

Then, build and install Nginx:

$ make -j4
$ make install

Finally, verify that the produced binary has been compiled with ngx_wasm_module:

$ nginx -V # output should contain '--add-module=/path/to/ngx_wasm_module'

Make sure that the nginx binary in your $PATH is the one that you just installed, or else specify the intended binary appropriately to the shell (e.g. $ /path/to/nginx ...).

Back to TOC

Examples

Configure Nginx and ngx_wasm_module with libwasmtime:

$ export NGX_WASM_RUNTIME=wasmtime

# statically linked
$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --with-cc-opt='-I/path/to/wasmtime/include' \
    --with-ld-opt='/path/to/wasmtime/lib/libwasmtime.a'

# dynamically linked
$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --with-cc-opt='-I/path/to/wasmtime/include' \
    --with-ld-opt='-L/path/to/wasmtime/lib -lwasmtime'

Configure Nginx and ngx_wasm_module with libwasmer:

$ export NGX_WASM_RUNTIME=wasmer

# statically linked
$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --with-cc-opt='-I/path/to/wasmer/include' \
    --with-ld-opt='/path/to/wasmer/lib/libwasmer.a'

# dynamically linked
$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --with-cc-opt='-I/path/to/wasmer/include' \
    --with-ld-opt='-L/path/to/wasmer/lib -lwasmer'

Configure Nginx and ngx_wasm_module with libwee8 (V8):

$ export NGX_WASM_RUNTIME=v8

# statically linked
$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --with-cc-opt='-I/path/to/v8/include' \
    --with-ld-opt='/path/to/v8/lib/libwee8.a -L/path/to/v8/lib'

You may also export the following environment variables and avoid having to specify --with-cc-opt and --with-ld-opt:

$ export NGX_WASM_RUNTIME={wasmtime,wasmer,v8} # defaults to wasmtime if unspecified
$ export NGX_WASM_RUNTIME_INC=/path/to/runtime/include
$ export NGX_WASM_RUNTIME_LIB=/path/to/runtime/lib
$ ./configure --add-module=/path/to/ngx_wasm_module

The following examples assume the above environment variables are still set.

Configure Nginx and ngx_wasm_module with a prefix and a few compiler options:

$ export NGX_WASM_RUNTIME={wasmtime,wasmer,v8}

$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --prefix=/usr/local/nginx \
    --with-cc-opt='-g -O3'

Configure Nginx and ngx_wasm_module without OpenSSL/PCRE/libz:

$ ./configure \
    --add-module=/path/to/ngx_wasm_module \
    --without-http_auth_basic_module \
    --without-http_rewrite_module \
    --without-http_gzip_module \
    --without-pcre

Back to TOC