What is OpenResty
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!