Skip to content

Latest commit

 

History

History
266 lines (197 loc) · 8.21 KB

INSTALL.md

File metadata and controls

266 lines (197 loc) · 8.21 KB
Raw

Installation Instructions

This document describes the steps to compile an Nginx/OpenResty release with ngx_wasmx_module as an addon. For instructions on the development environment of the module, consult DEVELOPER.md.

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. However, if you wish 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

1. 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 (i.e. OpenSSL, PCRE, zlib, and a compiler).

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

tar -xvf nginx-*.tar.gz

Back to TOC

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

3. ngx_wasmx_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_wasmx_module-*.tar.gz

Or use a local copy of this repository.

Back to TOC

4. Rust (optional)

The module configuration process (i.e. Nginx ./configure step) automatically builds a Rust library (lib/ngx-wasm-rs) as a bundled dependency when using Wasmer or V8. This library is not needed for Wasmtime, optional for Wasmer, and mandatory for V8.

  • rustup.rs is the easiest way to install Rust.

When optional (i.e. Wasmer), this library can be left out of the build by specifying the NGX_WASM_CARGO=0 environment variable. Note that some features such as .wat support will be missing.

See Build ngx-wasm-rs separately for building this library before the ./configure step, which can be required of some build environments bundling this module.

Back to TOC

Build

Configure Nginx with ngx_wasmx_module and link the Wasm runtime:

cd nginx-*
./configure \
  --add-module=/path/to/ngx_wasmx_module \
  --with-cc-opt='-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 Build 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_wasmx_module:

nginx -V # output should contain '--add-module=/path/to/ngx_wasmx_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

Build Examples

Configure Nginx and ngx_wasmx_module with libwasmtime:

export NGX_WASM_RUNTIME=wasmtime

# statically linked
./configure \
  --add-module=/path/to/ngx_wasmx_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_wasmx_module \
  --with-cc-opt='-I/path/to/wasmtime/include' \
  --with-ld-opt='-L/path/to/wasmtime/lib -lwasmtime'

Configure Nginx and ngx_wasmx_module with libwasmer:

export NGX_WASM_RUNTIME=wasmer

# statically linked
./configure \
  --add-module=/path/to/ngx_wasmx_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_wasmx_module \
  --with-cc-opt='-I/path/to/wasmer/include' \
  --with-ld-opt='-L/path/to/wasmer/lib -lwasmer'

Configure Nginx and ngx_wasmx_module with libwee8 (V8):

export NGX_WASM_RUNTIME=v8

# statically linked
./configure \
  --add-module=/path/to/ngx_wasmx_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 the Wasm runtime through --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_wasmx_module

For brevity, the following examples assume the above environment variables are still set.

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

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

Configure Nginx and ngx_wasmx_module without OpenSSL/PCRE/libz:

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

Back to TOC

Build ngx-wasm-rs separately

The lib/ngx-wasm-rs library is not required for Wasmtime builds, optional for Wasmer, and mandatory for V8. By default, the Nginx ./configure step will invoke cargo and conveniently build this library in the build prefix.

You may externalize the cargo build step of this library prior to running ./configure. Once the ngx-wasm-rs library built, run ./configure with the following tweaks:

  1. Set the NGX_WASM_CARGO=0 environment variable so that it does not run cargo itself.
  2. Specify compiler and linker flags to the library you compiled via the --with-cc-opt and --with-ld-opt arguments.

The example below uses a static build of ngx-wasm-rs located in some path /.../include and /.../lib:

export NGX_WASM_RUNTIME={wasmer,v8}

# statically linked
NGX_WASM_CARGO=0 ./configure \
  --add-module=/path/to/ngx_wasmx_module \
  --with-cc-opt='-I/.../include' \
  --with-ld-opt='/.../lib/libngx_wasm_rs.a'

# dynamically linked
NGX_WASM_CARGO=0 ./configure \
  --add-module=/path/to/ngx_wasmx_module \
  --with-cc-opt='-I/.../include' \
  --with-ld-opt='-L/.../lib -Wl,-rpath=/.../lib -lngx_wasm_rs'

If you are installing the dynamic library to a system location known to the system's dynamic linker such as /usr/lib or /usr/local/lib, it is not necessary to pass the -Wl,-rpath flag.

Note: The cargo build --features flag used when building ngx-wasm-rs must match the ones expected by ngx_wasmx_module:

  • With V8: --features wat.
  • With Wasmer: default feature set.

Note: (Wasmer only) Due to a limitation when linking multiple static libraries written in Rust that were compiled with different compilers, you typically cannot link an upstream static library of Wasmer with a static build of ngx-wasm-rs built with your local Rust compiler; in this case you have to combine the static Wasmer library with a dynamic ngx-wasm-rs library.

Back to TOC