How To Install OpenResty on Fedora 41

OpenResty has emerged as a powerful web platform for developers seeking high-performance solutions for their web applications. By extending the traditional Nginx architecture with LuaJIT integration, OpenResty enables the creation of dynamic, scalable web services that can handle complex tasks efficiently. If you’re running Fedora 41, this comprehensive guide will walk you through the entire installation process, configuration steps, and best practices to get OpenResty up and running smoothly on your system.

What is OpenResty?

OpenResty is a full-fledged web application platform that seamlessly integrates the standard Nginx core with LuaJIT (Just-In-Time Compiler for Lua). This powerful combination allows developers to extend Nginx’s capabilities through Lua scripting, enabling the creation of sophisticated web applications, APIs, and services directly within the web server environment.

Unlike traditional web servers that require external application servers, OpenResty embeds Lua directly into Nginx’s processing cycle. This architecture eliminates the overhead of inter-process communication typically found in other web server setups. The result is significantly improved performance, reduced latency, and enhanced scalability for web applications.

OpenResty’s key advantages include:

• High performance through Nginx’s event-driven architecture
• Simplified development workflow with Lua scripting
• Reduced resource consumption compared to traditional setups
• Built-in support for WebSockets, HTTP/2, and other modern protocols
• Extensive module ecosystem for additional functionality

Many organizations deploy OpenResty as an API gateway, load balancer, content cache, or microservices facilitator due to its exceptional performance characteristics and flexibility.

Prerequisites for Installation

Before proceeding with the OpenResty installation on Fedora 41, ensure your system meets the following requirements:

• A Fedora 41 system with system updates applied
• Root or sudo privileges for installation and configuration
• Basic familiarity with terminal commands
• Minimum 1GB RAM (2GB or more recommended for production use)
• At least 1GB free disk space
• Active internet connection for package downloads

If you have an existing Nginx installation, you should disable and stop it before installing OpenResty to prevent port conflicts and configuration issues:

sudo systemctl disable nginx
sudo systemctl stop nginx

It’s also advisable to update your system packages to ensure compatibility with the latest OpenResty version:

sudo dnf update -y

Installation Methods

There are two primary methods to install OpenResty on Fedora 41: using the official repository (recommended) or building from source. We’ll cover both approaches in detail.

Method 1: Using Official Repository

Installing OpenResty using the official repository is the simplest and most reliable method for most users. This approach ensures you receive official packages that are optimized for Fedora and can be easily updated in the future.

1. First, install the necessary prerequisite packages:

sudo dnf install -y wget dnf-plugins-core

2. Add the OpenResty repository to your system:

wget https://openresty.org/package/fedora/openresty.repo
sudo mv openresty.repo /etc/yum.repos.d/

3. Update the package index to include the new repository:

sudo dnf check-update

4. Install the core OpenResty package:

sudo dnf install -y openresty

5. Install additional useful OpenResty tools:

sudo dnf install -y openresty-resty openresty-opm

The openresty-resty package provides the resty command-line utility for running Lua scripts, while openresty-opm installs the OpenResty Package Manager, which allows you to easily manage and install OpenResty modules.

6. Verify the installation:

openresty -v

This command should display the OpenResty version, confirming a successful installation.

Method 2: Building from Source

Building OpenResty from source provides greater control over compilation options and module selection. This approach is recommended for advanced users who need specific customizations or the latest features not yet available in packaged versions.

1. Install build dependencies:

sudo dnf install -y gcc gcc-c++ make pcre-devel openssl-devel zlib-devel perl

2. Download the latest OpenResty source code:

wget https://openresty.org/download/openresty-1.21.4.2.tar.gz
tar -xzf openresty-1.21.4.2.tar.gz
cd openresty-1.21.4.2

3. Configure the build with desired options:

./configure \
  --prefix=/usr/local/openresty \
  --with-luajit \
  --with-pcre-jit \
  --with-ipv6 \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_realip_module \
  --with-http_stub_status_module

You can customize the configuration based on your needs. The options above enable common features like HTTP/2, IPv6 support, and SSL.

4. Compile and install OpenResty:

make -j$(nproc)
sudo make install

5. Create symbolic links for convenience:

sudo ln -s /usr/local/openresty/bin/openresty /usr/local/bin/
sudo ln -s /usr/local/openresty/bin/resty /usr/local/bin/

6. Create a systemd service file for OpenResty:

sudo nano /etc/systemd/system/openresty.service

Add the following content:

[Unit]
Description=The OpenResty Application Platform
After=network.target

[Service]
Type=forking
PIDFile=/usr/local/openresty/nginx/logs/nginx.pid
ExecStartPre=/usr/local/openresty/nginx/sbin/nginx -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/local/openresty/nginx/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/local/openresty/nginx/sbin/nginx -g 'daemon on; master_process on;' -s reload
ExecStop=/bin/kill -s QUIT $MAINPID
TimeoutStopSec=5
KillMode=mixed

[Install]
WantedBy=multi-user.target

7. Enable and start the OpenResty service:

sudo systemctl daemon-reload
sudo systemctl enable openresty
sudo systemctl start openresty

Building from source offers advantages like custom compilation flags, inclusion of specific modules, and the latest feature access. However, it requires manual updates and more maintenance compared to the repository method.

Basic Configuration

After installing OpenResty, the next step is configuring it to suit your requirements. The configuration structure is similar to Nginx, with some OpenResty-specific additions.

Configuration File Structure

The main configuration files are located in different directories depending on your installation method:

• Repository installation: /etc/openresty/
• Source installation: /usr/local/openresty/nginx/conf/

The primary configuration file is nginx.conf, which contains server-wide settings. For a cleaner organization, it’s recommended to use the conf.d directory for specific configurations:

sudo mkdir -p /etc/openresty/conf.d

Edit the main configuration file to include this directory:

sudo nano /etc/openresty/nginx.conf

Add the following line inside the http block:

include /etc/openresty/conf.d/*.conf;

Creating a Basic Server Configuration

Let’s create a simple configuration file to serve a website:

sudo nano /etc/openresty/conf.d/example.conf

Add the following content:

server {
    listen 80;
    server_name example.com;
    
    access_log /var/log/openresty/example_access.log;
    error_log /var/log/openresty/example_error.log;
    
    root /var/www/example;
    index index.html;
    
    location / {
        try_files $uri $uri/ =404;
    }
}

Create the necessary directories:

sudo mkdir -p /var/log/openresty
sudo mkdir -p /var/www/example

Create a simple HTML file to test the configuration:

sudo nano /var/www/example/index.html

Add some basic HTML content:

<!DOCTYPE html>
<html>
<head>
    <title>OpenResty on Fedora 41</title>
</head>
<body>
    <h1>OpenResty is running successfully!</h1>
    <p>If you can see this page, your OpenResty installation is working properly.</p>
</body>
</html>

Set the correct permissions:

sudo chown -R nobody:nobody /var/www/example

Configuration with Lua Scripts

One of OpenResty’s key features is Lua scripting integration. Here’s a simple example of how to use Lua within your configuration:

sudo nano /etc/openresty/conf.d/lua-example.conf

Add the following content:

server {
    listen 8080;
    server_name localhost;
    
    location /hello {
        default_type text/html;
        content_by_lua_block {
            ngx.say("<h1>Hello from OpenResty!</h1>")
            ngx.say("<p>The time is: ", os.date(), "</p>")
        }
    }
}

This configuration creates a server listening on port 8080 that responds with a dynamic “Hello” message including the current time.

Starting and Managing OpenResty

Managing OpenResty on Fedora 41 is straightforward using systemd commands.

Starting OpenResty

To start the OpenResty service:

sudo systemctl start openresty

Enabling Automatic Start

To ensure OpenResty starts automatically when your system boots:

sudo systemctl enable openresty

Checking Service Status

To verify that OpenResty is running properly:

sudo systemctl status openresty

This will display information about the running service, including any errors or warnings.

Reloading Configuration

After making changes to your configuration files, you need to reload OpenResty for the changes to take effect:

sudo systemctl reload openresty

This command performs a graceful reload without dropping active connections.

Stopping OpenResty

To stop the OpenResty service:

sudo systemctl stop openresty

Restarting OpenResty

If you need to completely restart the service:

sudo systemctl restart openresty

Testing Your Installation

After configuring OpenResty, it’s important to test that it’s working correctly. Here are several methods to verify your installation.

Testing Basic HTTP Response

Use curl to test HTTP responses:

curl -i http://localhost

If you configured the Lua example above:

curl -i http://localhost:8080/hello

You should see an HTTP 200 response with the expected content.

Creating a Simple Lua Application

Let’s create a more substantial Lua application to test OpenResty’s capabilities:

sudo mkdir -p /usr/local/openresty/lua
sudo nano /usr/local/openresty/lua/test.lua

Add the following Lua code:

local _M = {}

function _M.hello()
    ngx.header.content_type = "application/json"
    ngx.say('{"status":"success","message":"Hello from OpenResty Lua!","time":"' .. os.date() .. '"}')
end

return _M

Now create a configuration file to use this Lua module:

sudo nano /etc/openresty/conf.d/test-app.conf

Add the following content:

server {
    listen 8081;
    server_name localhost;
    
    lua_package_path "/usr/local/openresty/lua/?.lua;;";
    
    location /api/hello {
        content_by_lua_block {
            local test = require("test")
            test.hello()
        }
    }
}

Reload OpenResty and test your application:

sudo systemctl reload openresty
curl -i http://localhost:8081/api/hello

You should receive a JSON response with the current time.

Checking Logs for Issues

If you encounter any problems, check the error logs:

sudo tail -f /var/log/openresty/error.log

For specific virtual host logs (if configured):

sudo tail -f /var/log/openresty/example_error.log

Advanced Configuration

Once you have OpenResty running with a basic setup, you can explore more advanced configurations to enhance functionality and performance.

Setting Up Virtual Hosts

Virtual hosts allow you to host multiple websites on a single server. Create a configuration file for each site:

sudo nano /etc/openresty/conf.d/site1.conf

Add a virtual host configuration:

server {
    listen 80;
    server_name site1.example.com;
    
    root /var/www/site1;
    index index.html;
    
    access_log /var/log/openresty/site1_access.log;
    error_log /var/log/openresty/site1_error.log;
    
    location / {
        try_files $uri $uri/ =404;
    }
}

Configuring SSL/TLS

To secure your website with HTTPS:

sudo nano /etc/openresty/conf.d/secure-site.conf

Add the following configuration:

server {
    listen 443 ssl http2;
    server_name secure.example.com;
    
    ssl_certificate /etc/ssl/certs/example.crt;
    ssl_certificate_key /etc/ssl/private/example.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    
    root /var/www/secure-site;
    index index.html;
    
    # HTTP to HTTPS redirect
    location / {
        try_files $uri $uri/ =404;
    }
}

server {
    listen 80;
    server_name secure.example.com;
    return 301 https://$host$request_uri;
}

Performance Tuning

For optimal performance, consider these settings:

worker_processes auto;  # Set to number of CPU cores
worker_connections 2048;  # Increase for high-traffic sites

# File descriptor limits
worker_rlimit_nofile 30000;

# Keepalive settings
keepalive_timeout 65;
keepalive_requests 1000;

# Buffer sizes
client_body_buffer_size 128k;
client_max_body_size 10m;
client_header_buffer_size 1k;
large_client_header_buffers 4 4k;

# Timeouts
client_body_timeout 12;
client_header_timeout 12;
send_timeout 10;

Load Balancing Configuration

OpenResty can function as a load balancer:

upstream backend {
    server backend1.example.com weight=5;
    server backend2.example.com weight=5;
    server backup.example.com backup;
}

server {
    listen 80;
    server_name loadbalancer.example.com;
    
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Troubleshooting Common Issues

Even with careful installation and configuration, you might encounter issues. Here are solutions to common problems:

Permission Denied Errors

If you see permission denied errors in the logs:

2025/03/15 12:22:00 [crit] 12345#0: *1 open() "/var/www/html/index.html" failed (13: Permission denied)

Fix it with:

sudo chmod -R 755 /var/www/html
sudo chown -R nobody:nobody /var/www/html

Address Already in Use

If OpenResty fails to start with “address already in use” errors:

sudo fuser -k 80/tcp
sudo fuser -k 443/tcp

Then restart OpenResty:

sudo systemctl restart openresty

Configuration Syntax Errors

Test your configuration before reloading:

sudo openresty -t

This will identify syntax errors before applying changes.

Module Loading Issues

If Lua modules fail to load, check your lua_package_path directive and ensure the module exists at the specified location.

Log Analysis for Debugging

Enable debug-level logging temporarily to diagnose issues:

error_log /var/log/openresty/error.log debug;

Then watch the logs in real-time:

sudo tail -f /var/log/openresty/error.log

Remember to change the log level back to a more appropriate level (info, warn, or error) after debugging.

Real-World Applications and Use Cases

OpenResty excels in several real-world scenarios:

API Gateway Implementation

OpenResty makes an excellent API gateway with features like:

location /api/ {
    access_by_lua_block {
        -- API key validation
        local api_key = ngx.req.get_headers()["X-API-Key"]
        if not api_key or api_key ~= "valid_key" then
            ngx.status = 401
            ngx.say('{"error":"Unauthorized"}')
            return ngx.exit(401)
        end
    }
    
    proxy_pass http://backend_api_server;
}

Content Filtering and Transformation

OpenResty can modify responses on-the-fly:

location /filtered-content/ {
    proxy_pass http://content_server;
    
    header_filter_by_lua_block {
        ngx.header.content_length = nil
    }
    
    body_filter_by_lua_block {
        local chunk = ngx.arg[1]
        -- Replace sensitive information
        if chunk then
            chunk = string.gsub(chunk, "sensitive%-data", "REDACTED")
            ngx.arg[1] = chunk
        end
    }
}

Rate Limiting

Implement rate limiting to protect your application:

http {
    lua_shared_dict limits 10m;
    
    server {
        location / {
            access_by_lua_block {
                local limit_req = require "resty.limit.req"
                local lim, err = limit_req.new("limits", 10, 5)
                if not lim then
                    ngx.log(ngx.ERR, "failed to instantiate rate limiter: ", err)
                    return ngx.exit(500)
                end
                
                local key = ngx.var.binary_remote_addr
                local delay, err = lim:incoming(key, true)
                
                if not delay then
                    if err == "rejected" then
                        return ngx.exit(429)
                    end
                    ngx.log(ngx.ERR, "failed to limit request: ", err)
                    return ngx.exit(500)
                end
            }
            
            # Regular content serving here
        }
    }
}

Maintenance and Updates

Maintaining your OpenResty installation ensures security and optimal performance.

Keeping OpenResty Updated

To update OpenResty installed from the repository:

sudo dnf check-update
sudo dnf update openresty

For source installations, download the new version and repeat the build process.

Managing Dependencies

Keep system libraries updated:

sudo dnf update

For Lua modules managed with OPM:

opm update --all

Backup Strategies

Regularly back up your configuration files:

sudo cp -r /etc/openresty /etc/openresty.bak-$(date +%Y%m%d)

Consider using version control for configuration management:

cd /etc/openresty
sudo git init
sudo git add .
sudo git commit -m "Initial configuration"

Congratulations! You have successfully installed OpenResty. Thanks for using this tutorial for installing OpenResty on Fedora 41 system. For additional help or useful information, we recommend you check the official OpenResty website.