Quick Start Guide

This guide will walk you through the basic steps to get an OpenResty container running on your machine.

Prerequisites

Ensure you have Docker installed and running on your system.

Step 1: Pull an OpenResty Image

First, pull a recommended image from Docker Hub. The Debian Bookworm image is a great general-purpose choice.

docker pull openresty/openresty:bookworm

You can see a full list of available images in the Image Tags & Pulling section.

Step 2: Run a Container

Run a container in detached mode (-d) and map your local port 8080 to the container's port 80.

docker run --rm -d -p 8080:80 --name my-openresty openresty/openresty:bookworm
  • --rm: Automatically removes the container when it exits.
  • -d: Runs the container in the background.
  • -p 8080:80: Maps port 8080 on the host to port 80 in the container.
  • --name my-openresty: Assigns a convenient name to the container.

Step 3: Verify It's Running

You can now send a request to the server using curl or your web browser.

curl http://localhost:8080

You should see the default Nginx welcome page HTML as a response.

Step 4: Serving Custom Content

To serve your own files, you can use a Docker volume to mount a local directory into the container's web root (/usr/local/openresty/nginx/html).

  1. Create a local directory and a sample index.html file.

    mkdir -p my-app/html
echo "<h1>Hello from Docker OpenResty!</h1>" > my-app/html/index.html

  2. Stop the previous container.

    docker stop my-openresty

  3. Run a new container, mounting your my-app/html directory.

    docker run --rm -d -p 8080:80 \ 
  -v "$(pwd)/my-app/html:/usr/local/openresty/nginx/html:ro" \ 
  --name my-openresty openresty/openresty:bookworm
    Note: :ro makes the volume read-only inside the container, which is a good security practice.

  4. Verify again by sending a request.

    curl http://localhost:8080

    This time, you should see your custom message: <h1>Hello from Docker OpenResty!</h1>.

Next Steps