OpenResty is a powerful web platform that enhances the standard Nginx web server with LuaJIT and a collection of useful Lua libraries. Think of it as Nginx on steroids – it combines the rock-solid performance of Nginx with the flexibility of Lua scripting, making it an excellent choice for building high-performance web applications, APIs, and microservices.

Key Features of OpenResty

OpenResty brings several compelling features to the table that make it stand out from traditional web servers. You get access to embedded Lua scripting capabilities, which means you can write custom logic directly in your web server configuration. This eliminates the need for separate application servers in many scenarios.

The platform includes built-in support for Redis, MySQL, PostgreSQL, and memcached connections, making database integration seamless. Plus, it offers excellent performance characteristics – we’re talking about handling tens of thousands of concurrent connections with minimal resource overhead.

Why Choose OpenResty Over Standard Nginx?

While Nginx is fantastic for serving static content and basic reverse proxying, OpenResty takes things further. You can implement complex business logic, real-time data processing, and dynamic content generation without leaving the web server layer. This reduces latency and simplifies your architecture significantly.

Prerequisites for Installing OpenResty on Ubuntu

System Requirements

Before diving into the installation process, let’s make sure your system meets the basic requirements. You’ll need a Ubuntu system with at least 1GB of RAM and sufficient disk space. OpenResty works on both x86_64 (AMD64) and ARM64 architectures, so whether you’re running on a traditional server or ARM-based cloud instances, you’re covered.

Checking Your Ubuntu Version

The installation process varies slightly depending on your Ubuntu version. Run this command to check your version:

lsb_release -a

This information is crucial because Ubuntu 22 and later versions handle GPG keys differently than earlier versions.

Stopping Existing Web Servers

If you have Apache or Nginx already running, you’ll need to stop and disable them to avoid port conflicts. Here’s how:

sudo systemctl stop nginx apache2
sudo systemctl disable nginx apache2

Method 1: Installing OpenResty via APT Repository

The APT repository method is the most straightforward approach and what I recommend for most users. It handles dependencies automatically and makes future updates much easier.

Step 1: Update System Packages

Start by updating your system packages to ensure you have the latest security patches and dependencies:

sudo apt update && sudo apt upgrade -y

Step 2: Install Required Dependencies

Install the packages needed for the OpenResty installation process:

sudo apt install -y --no-install-recommends wget gnupg ca-certificates lsb-release software-properties-common

These tools are essential for downloading and verifying the OpenResty packages.

Step 3: Import OpenResty GPG Key

The GPG key ensures the authenticity of the packages you’re downloading. The process differs based on your Ubuntu version.

For Ubuntu 16-20

Use the traditional apt-key method:

wget -O - https://openresty.org/package/pubkey.gpg | sudo apt-key add -

For Ubuntu 22 and Later

Ubuntu 22+ uses a different approach for managing GPG keys:

wget -O - https://openresty.org/package/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openresty.gpg

Step 4: Add OpenResty Repository

Now you need to add the official OpenResty repository to your system. The exact command depends on your system architecture.

For x86_64/AMD64 Systems

For Ubuntu 16-20:

echo "deb http://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list

For Ubuntu 22 and later:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list > /dev/null

For ARM64/AArch64 Systems

For Ubuntu 16-20:

echo "deb http://openresty.org/package/arm64/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list

For Ubuntu 22 and later:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/arm64/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list > /dev/null

Step 5: Install OpenResty Package

Update your package index and install OpenResty:

sudo apt update
sudo apt install -y openresty

If you prefer a minimal installation without recommended packages:

sudo apt install -y --no-install-recommends openresty

Step 6: Verify Installation

Check if OpenResty installed correctly by verifying the service status:

sudo systemctl status openresty

You should see output indicating that the service is active and running. You can also check the version:

openresty -V

Method 2: Building OpenResty from Source

While the APT method is recommended, building from source gives you more control over compilation options and module inclusion.

Downloading Source Code

First, download the latest OpenResty source code from the official website:

wget https://openresty.org/download/openresty-VERSION.tar.gz
tar -xvf openresty-VERSION.tar.gz
cd openresty-VERSION/

Replace VERSION with the actual version number you downloaded.

Compilation Process

Configure and compile OpenResty:

./configure -j2
make -j2

The -j2 flag uses two CPU cores for faster compilation. Adjust this number based on your system’s capabilities.

Installation and Path Configuration

Install the compiled binaries and update your PATH:

sudo make install
echo 'export PATH=/usr/local/openresty/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Configuring OpenResty After Installation

Understanding Configuration Files

OpenResty configuration files are located in /etc/openresty/ when installed via APT, or /usr/local/openresty/nginx/conf/ when built from source. The main configuration file is nginx.conf, which follows standard Nginx syntax with additional Lua capabilities.

Creating Your First OpenResty Configuration

Let’s create a simple configuration to test your installation. Create a working directory structure:

mkdir -p /data/openresty/www/{logs,conf}
cd /data/openresty/www/

Create a basic nginx.conf file in the conf directory:

worker_processes 1;
error_log logs/error.log;
events {
    worker_connections 1024;
}
http {
    server {
        listen 8080;
        location / {
            default_type text/html;
            content_by_lua_block {
                ngx.say("<h1>Hello from OpenResty!</h1>")
                ngx.say("<p>Current time: " .. os.date() .. "</p>")
            }
        }
    }
}

Setting Up Directory Structure

A well-organized directory structure makes managing your OpenResty installation much easier. Create separate directories for logs, configuration files, SSL certificates, and any custom Lua modules you might develop.

Starting and Managing OpenResty Service

Starting OpenResty

If you installed via APT, use systemctl to manage the service:

sudo systemctl start openresty

For custom installations, start OpenResty manually:

/usr/local/openresty/nginx/sbin/nginx -p /data/openresty/www/ -c conf/nginx.conf

Enabling Auto-start

Ensure OpenResty starts automatically on system boot:

sudo systemctl enable openresty

Managing the Service

Common service management commands include:

sudo systemctl stop openresty      # Stop the service
sudo systemctl restart openresty   # Restart the service
sudo systemctl reload openresty    # Reload configuration
sudo systemctl status openresty    # Check status

Testing Your OpenResty Installation

Basic Connectivity Test

Test your installation with a simple curl command:

curl http://localhost:8080/

You should see the HTML output from your configuration file.

Creating a Hello World Example

The configuration we created earlier demonstrates OpenResty’s Lua capabilities. The content_by_lua_block directive allows you to write Lua code directly in the configuration file, which executes when handling requests.

Performance Testing

Use tools like ab (Apache Bench) or wrk to test performance:

sudo apt install apache2-utils
ab -n 1000 -c 10 http://localhost:8080/

This sends 1000 requests with 10 concurrent connections to measure throughput and response times.

Common Issues and Troubleshooting

Port Conflicts

If you get “Address already in use” errors, another service is using the same port. Check what’s running on your chosen port:

sudo netstat -tlnp | grep :8080

Change the port number in your configuration or stop the conflicting service.

Permission Issues

OpenResty needs proper permissions to access log files and bind to ports. Make sure the OpenResty user has appropriate permissions, and remember that binding to ports below 1024 requires root privileges.

Configuration Errors

Always test your configuration before reloading:

openresty -t -p /data/openresty/www/ -c conf/nginx.conf

This command checks for syntax errors without actually starting the server.

Security Best Practices

Firewall Configuration

Configure your firewall to only allow necessary ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

User Permissions

Run OpenResty as a non-privileged user whenever possible. The default installation typically creates an openresty user for this purpose.

Regular Updates

Keep OpenResty updated to receive security patches:

sudo apt update && sudo apt upgrade openresty

FAQs

Q: What’s the difference between OpenResty and regular Nginx?
A: OpenResty is built on Nginx but includes LuaJIT and additional modules that allow you to write custom logic directly in the web server configuration. This eliminates the need for separate application servers in many scenarios and provides better performance for dynamic content.

Q: Can I run OpenResty alongside Apache or Nginx?
A: Yes, but they cannot use the same ports simultaneously. You’ll need to configure them to listen on different ports or bind to different IP addresses. It’s generally better to choose one primary web server to avoid complexity.

Q: Is OpenResty suitable for production environments?
A: Absolutely! OpenResty is used by major companies like Cloudflare, Taobao, and many others in production. It’s designed for high-performance, high-concurrency scenarios and has proven reliability in demanding environments.

Q: How do I update OpenResty to a newer version?
A: If you installed via APT, simply run sudo apt update && sudo apt upgrade openresty. For source installations, you’ll need to download the new version, compile it, and replace the existing installation manually.

Q: Can I use existing Nginx configuration files with OpenResty?
A: Yes, OpenResty is fully compatible with standard Nginx configurations. You can migrate existing Nginx setups to OpenResty without changes, then gradually add Lua functionality as needed.

2741
Install OpenResty on Ubuntu
Technology
OpenResty, Ubuntu, Nginx, Web Server, Installation Guide, Linux