docker.recipes

OpenResty

intermediate

High-performance web platform based on NGINX and LuaJIT.

Overview

OpenResty is a high-performance web platform that combines the power of NGINX with the flexibility of Lua scripting through LuaJIT integration. Originally developed by Yichun Zhang (agentzh) at Cloudflare, OpenResty extends NGINX with a comprehensive set of Lua libraries and modules, enabling developers to build complex web applications, API gateways, and reverse proxies with embedded scripting capabilities. This makes it particularly valuable for scenarios requiring dynamic request processing, custom authentication logic, or real-time content transformation without the overhead of external application servers. This deployment provides a single OpenResty container based on the Alpine Linux image, configured with mounted directories for custom NGINX configurations and Lua modules. The setup exposes both HTTP (port 80) and HTTPS (port 443) endpoints, with persistent storage for configuration files in ./nginx/conf.d and Lua libraries in ./lua directories. The container runs as a standalone service with automatic restart capabilities, making it suitable for both development and production environments where you need NGINX's performance combined with Lua's programmability. This configuration is ideal for developers and DevOps teams who need more than traditional NGINX reverse proxying but want to avoid the complexity of separate application servers. It's particularly valuable for organizations building API gateways, implementing custom authentication flows, or requiring real-time request/response manipulation. The embedded Lua scripting environment provides access to the full ecosystem of lua-resty-* libraries for database connections, HTTP clients, and various protocol implementations.

Key Features

  • Full NGINX compatibility with embedded LuaJIT for high-performance scripting
  • Access to comprehensive lua-resty-* library ecosystem for Redis, MySQL, HTTP, and WebSocket clients
  • Built-in support for content_by_lua_block directives for inline request processing
  • Alpine-based container image providing minimal footprint with full OpenResty functionality
  • Dual HTTP/HTTPS port exposure with SSL/TLS termination capabilities
  • Persistent volume mounting for custom NGINX configurations and Lua module libraries
  • Integrated debugging capabilities through ngx.log() functions for Lua code troubleshooting
  • Support for complex API gateway patterns including rate limiting, authentication, and request transformation

Common Use Cases

  • 1Building high-performance API gateways with custom authentication and rate limiting logic
  • 2Implementing dynamic reverse proxy configurations based on request headers or user attributes
  • 3Creating real-time content transformation and aggregation services for microservices architectures
  • 4Developing custom load balancers with health checking and failover logic written in Lua
  • 5Building authentication proxies that validate JWT tokens or integrate with external identity providers
  • 6Creating CDN edge servers with custom caching strategies and content manipulation
  • 7Implementing WebSocket proxies with custom protocol handling and message transformation

Prerequisites

  • Docker and Docker Compose installed with at least 512MB available memory for the container
  • Basic understanding of NGINX configuration syntax and server block definitions
  • Familiarity with Lua programming language and OpenResty-specific APIs like ngx.* modules
  • Ports 80 and 443 available on the host system for HTTP/HTTPS traffic
  • Knowledge of lua-resty-* library ecosystem for database and HTTP client integrations
  • Understanding of NGINX phases and where Lua code execution fits in the request lifecycle

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  openresty: 
3    image: openresty/openresty:alpine
4    container_name: openresty
5    restart: unless-stopped
6    volumes: 
7      - ./nginx/conf.d:/etc/nginx/conf.d:ro
8      - ./lua:/usr/local/openresty/site/lualib:ro
9    ports: 
10      - "80:80"
11      - "443:443"
12    networks: 
13      - openresty-network
14
15networks: 
16  openresty-network: 
17    driver: bridge

.env Template

.env
1# OpenResty configuration

Usage Notes

  1. 1Docs: https://openresty.org/en/docs.html
  2. 2Full NGINX compatibility plus Lua scripting via content_by_lua_block
  3. 3Place Lua modules in /usr/local/openresty/site/lualib/
  4. 4Use lua-resty-* libraries for Redis, MySQL, HTTP clients
  5. 5Great for API gateways, auth logic, request transformation
  6. 6Debug with ngx.log(ngx.ERR, 'message') in Lua code

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  openresty:
5    image: openresty/openresty:alpine
6    container_name: openresty
7    restart: unless-stopped
8    volumes:
9      - ./nginx/conf.d:/etc/nginx/conf.d:ro
10      - ./lua:/usr/local/openresty/site/lualib:ro
11    ports:
12      - "80:80"
13      - "443:443"
14    networks:
15      - openresty-network
16
17networks:
18  openresty-network:
19    driver: bridge
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24# OpenResty configuration
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/openresty/run | bash

Troubleshooting

  • nginx: [emerg] cannot load certificate: Ensure SSL certificate files are properly mounted and accessible within the container filesystem
  • lua entry thread aborted: runtime error: Check ngx.log(ngx.ERR) outputs and verify Lua syntax in your content_by_lua_block directives
  • module 'resty.redis' not found: Verify lua-resty-redis library is installed or available in the /usr/local/openresty/site/lualib/ directory
  • failed to run header_filter_by_lua: Ensure Lua code in header processing phases doesn't attempt to access request body or response content
  • connect() failed (111: Connection refused) while connecting to upstream: Check that upstream services referenced in Lua code are accessible from the openresty-network
  • OpenResty container exits immediately: Validate NGINX configuration syntax in mounted conf.d files using nginx -t before container startup

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

openresty

Tags

#openresty#nginx#lua#api-gateway#performance

Category

Web Servers & Reverse Proxies

Related Recipes

Ad Space