Skip to content

What is OpenResty

homepage-banner

Introduction

OpenResty is a powerful web application server that is built on top of the Nginx web server. It provides a lot of functionalities that are not available in the standard Nginx server, including Lua-based scripting capabilities, load balancing, and more. In this blog post, we’ll take a closer look at OpenResty and provide a step-by-step guide on how to set up and configure a basic OpenResty server in just 30 minutes.

Installing OpenResty

To get started with OpenResty, the first thing you need to do is to install it on your machine. Installation is relatively straightforward and can be done using your machine’s package manager, or by downloading the source code directly. Once installed, you can start the OpenResty server by running the nginx command.

OpenResty provides official pre-built packages for some common Linux distributions, such as Ubuntu, Debian, CentOS, RHEL, Fedora, OpenSUSE, Alpine, and Amazon Linux. If you are using Linux, make sure to check out these binary packages first.

For Win32, pre-built OpenResty packages are available on the Download page. Make sure to also refer to this documentation instead.

If you are using Mac OS X or macOS, we highly recommend using the homebrew package manager to install OpenResty, as follows:

brew install openresty/brew/openresty

If you already installed OpenResty from homebrew/nginx, please run the following command first:

brew untap homebrew/nginx

Building from Source

If you haven’t downloaded the OpenResty source code tarball yet, please go to the https://openresty.org/en/download.html page first.

Building and installing OpenResty is typically a simple process, which involves the following steps:

tar -xvf openresty-VERSION.tar.gz
cd openresty-VERSION/
./configure -j2
make -j2
sudo make install

# better also add the following line to your ~/.bashrc or ~/.bash_profile file.
export PATH=/usr/local/openresty/bin:$PATH

Replace VERSION with a specific version number of OpenResty, such as 1.11.2.5.

You can add 3rd-party NGINX modules or enable other NGINX core features just like with the standard NGINX distribution. For example, you can use OpenResty’s ./configure tool with the --add-module=PATH or --add-dynamic-module=PATH options to include 3rd-party NGINX C modules. However, please note that 3rd-party NGINX C modules not maintained by OpenResty are not supported by OpenResty and they may compromise OpenResty’s stability.

Use the command ./configure --help to view all available options to enable and/or disable certain components or features of OpenResty during build time.

To start OpenResty, use the openresty command instead of the original nginx command, provided that the <openresty-prefix>/bin/ directory has been correctly added to your system environment PATH. The default <openresty-prefix> is /usr/local/openresty/ unless overridden by the --prefix=PATH option of ./configure.

You can also use the resty command-line utility to run a headless OpenResty program or the restydoc tool to browse OpenResty documentation in the terminal.

If your system environment is modern enough, you should generally enable PCRE JIT support and IPv6 support in your NGINX by passing the --with-pcre-jit and --with-ipv6 options to the ./configure script.

./configure --with-pcre-jit --with-ipv6

By default, OpenResty is installed into the prefix /usr/local/openresty/.

Finally, you need to add the command-line utilities provided by OpenResty to your PATH environment, as in

export PATH=/usr/local/openresty/bin:/usr/local/openresty/nginx/sbin:$PATH

if you are using bash. Better add this line to your shell’s startup script, like ~/.bashrc or ~/.bash_profile.

If you have problems while building or want finer control over the building process, please read on.

Prerequisites

You should have perl 5.6.1+, libpcre, libssl installed into your system. For Linux, you should also ensure that ldconfig is in your PATH environment.

Debian and Ubuntu users

You’re recommended to install the following packages using apt-get:

apt-get install libpcre3-dev \
    libssl-dev perl make build-essential curl

Fedora and RedHat users

You’re recommended to install the following packages using yum:

yum install pcre-devel openssl-devel gcc curl

Mac OS X (macOS) users

It is highly recommended to install OpenResty on our Mac OS X or macOS systems via homebrew package manager, like this:

brew install openresty/brew/openresty

If you already installed OpenResty from homebrew/nginx, please run the following command first:

brew untap homebrew/nginx

You’re recommended to install prerequisites PCRE and OpenSSL using some package management tool, like Homebrew:

brew update
brew install pcre openssl curl

Alternatively you can install PCRE and/or OpenSSL from source all by yourself

After installing PCRE and OpenSSL, you may need to specify the paths for their headers and libraries to your C compiler and linker, for example,

./configure \
   --with-cc-opt="-I/usr/local/opt/openssl/include/ -I/usr/local/opt/pcre/include/" \
   --with-ld-opt="-L/usr/local/opt/openssl/lib/ -L/usr/local/opt/pcre/lib/" \
   -j8

assuming that your PCRE and OpenSSL are installed under the prefix /usr/local/opt/ which is the default for homebrew.

FreeBSD users

You need to install the following ports:

  • devel/gmake
  • security/openssl
  • devel/pcre

Building OpenResty

Download

download the latest openresty tarball can be fetched from the https://openresty.org/en/download.html page and unpack it like this:

tar -xzvf openresty-VERSION.tar.gz

where VERSION should be replaced by real version numbers like 1.11.2.5.

./configure

Then enter the openresty-VERSION/ directory, and type the following command to configure:

./configure

By default, --prefix=/usr/local/openresty is assumed. You should only disable LuaJIT 2 when your platform does not support LuaJIT.

You can specify various options, as in

./configure --prefix=/opt/openresty \
            --with-pcre-jit \
            --with-ipv6 \
            --without-http_redis2_module \
            --with-http_iconv_module \
            --with-http_postgres_module \
            -j8

All of the standard options for the Nginx configuration file can be used here, including --add-module=PATH for adding your own third-party Nginx C modules. To see more options available, try ./configure --help.

If there are any errors when running the ./configure script, you can find them in the file build/nginx-VERSION/objs/autoconf.err, where VERSION should be replaced by a concrete version number of OpenResty, like 1.11.2.5.

Notes for Solaris Users

For Solaris users, it is common to install libraries like OpenSSL to /lib. If you receive a complaint about missing OpenSSL and you have already installed it, specify the --with-ld-opt='-L/lib' option.

make

Now you can compile everything using the following command:

make

If your machine has multiple cores and your make supports the jobserver feature, you can compile things in parallel like this:

make -j2

assuming you have 2 CPU cores.

make install

If all the previous steps go without problems, you can install OpenResty into your system by typing the command

make install

On Linux, it often requires sudo to gain root access.

If you prefer building the OpenSSL and PCRE dependencies from their source tarballs, then you could follow the commands below (you may want to change the version number accordingly):

wget https://www.openssl.org/source/openssl-1.0.2k.tar.gz
tar -zvxf openssl-1.0.2k.tar.gz
cd openssl-1.0.2k/
patch -p1 < /path/to/openresty/patches/openssl-1.0.2h-sess_set_get_cb_yield.patch
cd ..

wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.40.tar.gz
tar -xvf pcre-8.40.tar.gz

wget https://openresty.org/download/openresty-1.11.2.5.tar.gz
tar -zxvf openresty-1.11.2.5.tar.gz
cd openresty-1.11.2.5/

## assuming your have 4 spare logical CPU cores

./configure --with-openssl=../openssl-1.0.2k \
                 --with-pcre=../pcre-8.40 -j4
make -j8
sudo make install

Configuring OpenResty

After installing OpenResty, the next step is to configure it. OpenResty uses a configuration file to specify how it should handle incoming requests. The configuration file is located in the conf directory of your OpenResty installation. By default, the configuration file is named nginx.conf.

Some of the key configurations you can set in the nginx.conf file include the server name, the listen port, the root directory for serving files, and more. You can also use Lua scripts to add custom functionality to your server.

Using OpenResty

Once OpenResty is installed and configured, you can start using it to serve web applications. You can create Lua scripts to handle incoming requests, and you can use the location directive in your nginx.conf file to specify which scripts should be used for which requests.

OpenResty also provides a lot of built-in functionality that you can use to enhance your web applications. For example, you can use the ngx.balancer Lua module to implement load balancing across multiple backend servers, or you can use the ngx.req module to manipulate incoming requests.

Conclusion

In conclusion, OpenResty is a powerful web application server that offers a lot of functionality and flexibility. It can be used to serve web applications of all sizes, and it is relatively easy to set up and configure. By following the steps outlined in this guide, you should be able to get up and running with OpenResty in just 30 minutes. Happy coding!

Leave a message