Building from Source

Building from source provides the ultimate flexibility to customize your OpenResty installation. This approach is ideal when you need to add custom Nginx modules, apply patches, or alter the build configuration.

How It Works

The source-based Dockerfiles (e.g., alpine/Dockerfile, jammy/Dockerfile) automate the process of:

  1. Installing build dependencies (build-essential, libgd-dev, etc.).
  2. Downloading and compiling dependencies like OpenSSL and PCRE2.
  3. Downloading the OpenResty source tarball.
  4. Running the ./configure script with a set of options.
  5. Compiling and installing OpenResty.
  6. Cleaning up build dependencies to keep the final image small.

Getting Started

To build a custom image, first clone the repository:

git clone https://github.com/openresty/docker-openresty.git
cd docker-openresty

Then, run the docker build command, specifying the Dockerfile for your desired base OS. For example, to build on Ubuntu Jammy:

docker build -t my-custom-openresty -f jammy/Dockerfile .

Customization with Build Arguments

The build process is controlled by a rich set of --build-arg variables. You can override these to customize the build.

Example: Adding a Custom Nginx Module

To add a module like ngx_http_echo_module, you would:

  1. Use RESTY_EVAL_PRE_CONFIGURE to clone the module's source code.
  2. Use RESTY_CONFIG_OPTIONS_MORE to add the --add-module flag to the configure script.
docker build -f jammy/Dockerfile \ 
  --build-arg RESTY_EVAL_PRE_CONFIGURE='cd /tmp && git clone https://github.com/agentzh/echo-nginx-module.git' \ 
  --build-arg RESTY_CONFIG_OPTIONS_MORE='--add-module=/tmp/echo-nginx-module' \ 
  -t openresty-with-echo .

Available Build Arguments

Here is a comprehensive list of build arguments for source-based builds:

Key Default Description
RESTY_IMAGE_BASE "ubuntu" / "alpine" The base Docker image to build FROM.
RESTY_IMAGE_TAG "noble" / "3.22.1" The base Docker image tag to build FROM.
RESTY_VERSION 1.27.1.2 The version of OpenResty to use.
RESTY_LUAROCKS_VERSION 3.12.2 The version of LuaRocks to use.
RESTY_OPENSSL_VERSION 3.4.1 The version of OpenSSL to use.
RESTY_OPENSSL_PATCH_VERSION 3.4.1 The version of OpenSSL to use when patching.
RESTY_OPENSSL_URL_BASE "https://github.com/openssl/openssl/releases/download/openssl-${RESTY_OPENSSL_VERSION}" The base of the URL to download OpenSSL from.
RESTY_OPENSSL_BUILD_OPTIONS "enable-camellia enable-seed ..." Options to tweak Resty's OpenSSL build.
RESTY_PCRE_VERSION 10.44 The version of PCRE2 to use.
RESTY_PCRE_SHA256 86b9cb0a... The SHA-256 checksum of the PCRE2 package.
RESTY_PCRE_BUILD_OPTIONS "--enable-jit --enable-pcre2grep-jit ..." Options to tweak Resty's PCRE build.
RESTY_PCRE_OPTIONS "--with-pcre-jit" Options to tweak Resty's build args regarding PCRE.
RESTY_J 1 Sets the parallelism level (-jN) for the builds.
RESTY_CONFIG_OPTIONS "--with-compat --without-http_rds_json_module ..." Options to pass to OpenResty's ./configure script.
RESTY_LUAJIT_OPTIONS "--with-luajit-xcflags='-DLUAJIT_NUMMODE=2 ...'" Options to tweak LuaJIT.
RESTY_CONFIG_OPTIONS_MORE "" More options to pass to OpenResty's ./configure script.
RESTY_ADD_PACKAGE_BUILDDEPS "" Additional packages to install for the build only.
RESTY_ADD_PACKAGE_RUNDEPS "" Additional packages to install for runtime.
RESTY_EVAL_PRE_CONFIGURE "" Command(s) to run before ./configure.
RESTY_EVAL_POST_DOWNLOAD_PRE_CONFIGURE "" Command(s) to run after downloading and extracting OpenResty source.
RESTY_EVAL_PRE_MAKE "" Command(s) to run before make install.
RESTY_EVAL_POST_MAKE "" Command(s) to run after make install.
RESTY_STRIP_BINARIES "" Set to non-zero to strip binaries (for -slim images).