Skip to content
Klutch.sh Docs

Deploying an OpenResty App

Introduction

OpenResty is a high-performance web platform built on Nginx and LuaJIT for dynamic server-side scripting. Deploying OpenResty with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for configs and logs—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample Lua code, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your OpenResty config and Dockerfile (GitHub is the only supported git source)
  • Domain and TLS if you serve HTTPS

For onboarding, see the Quick Start.

Architecture and ports

  • OpenResty serves HTTP on internal port 8080; choose HTTP traffic.
  • Persistent storage is optional for configs/logs; required if you store on-disk cache.

Repository layout

openresty/
├── Dockerfile              # Must be at repo root for auto-detection
├── nginx.conf              # Main config
├── conf.d/                 # Site configs
├── lua/                    # Lua scripts
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables or mounted files.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t openresty-local .
docker run -p 8080:8080 openresty-local

Dockerfile for OpenResty (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM openresty/openresty:1.21.4.3-alpine


ENV PORT=8080


WORKDIR /usr/local/openresty/nginx


COPY nginx.conf /usr/local/openresty/nginx/conf/nginx.conf
COPY conf.d /etc/nginx/conf.d
COPY lua /usr/local/openresty/lua


EXPOSE 8080
CMD ["openresty", "-g", "daemon off;"]

Notes:

  • Pin the image tag (e.g., 1.21.4.3-alpine) for stability; update intentionally.
  • Add any required system packages (apk add) if Lua modules need them.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=8080
  • Optional custom vars consumed in nginx.conf (e.g., upstream URLs, secrets via env directive).

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=openresty -g 'daemon off;'

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required) if you persist logs or cache:

  • /var/log/nginx — access and error logs.
  • /usr/local/openresty/nginx/cache — optional cache if configured.

Ensure these paths are writable.

Deploy OpenResty on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add any environment variables your config expects.
  5. Attach persistent volumes for /var/log/nginx (and cache paths if used), sizing them for your log and cache retention.
  6. Deploy. Your OpenResty instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample Lua handler

Add to lua/hello.lua and include in your nginx.conf or conf.d/site.conf:

local cjson = require "cjson.safe"
ngx.header.content_type = "application/json"
ngx.say(cjson.encode({ message = "Hello from OpenResty on Klutch.sh" }))

Example location block:

location /hello {
    content_by_lua_file /usr/local/openresty/lua/hello.lua;
}

Health checks and production tips

  • Add an HTTP probe to /health or /hello for readiness.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Keep secrets out of configs; inject via env vars and env directive or mounted files.
  • Monitor /var/log/nginx; rotate or resize volumes before they fill.
  • Pin image versions and test config changes in staging before production.

OpenResty on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and your Lua scripts in place, you can ship high-performance dynamic Nginx apps without extra YAML or workflow overhead.