ficusio/openresty repository overview

⁠OpenResty Docker image

This repository contains Dockerfiles for ficusio/openresty⁠ image, which has two flavors.

⁠Flavors

The main one is Alpine linux⁠-based ficusio/openresty:latest. Its virtual size is just 31MB, yet it contains a fully functional OpenResty⁠ bundle v1.9.3.1 and apk package manager⁠, which allows you to easily install lots of pre-built packages⁠.

The other flavor is ficusio/openresty:debian. It is based on debian:wheezy and thus is much bigger in size (256MB). It is mostly useful for NginX profiling, as it may not be easy to build different profiling tools with musl libc⁠, which is used in Alpine Linux.

⁠Paths & config

NginX is configured with /opt/openresty/nginx prefix path⁠, which means that, by default, it loads configuration from /opt/openresty/nginx/conf/nginx.conf file. The default HTML root path is /opt/openresty/nginx/html/.

OpenResty bundle includes several useful Lua modules located in /opt/openresty/lualib/ directory. This directory is already present in Lua package path, so you don't need to specify it in NginX lua_package_path directive.

The Lua NginX module is built with LuaJIT 2.1, which is also available as stand-alone lua binary.

NginX stores various temporary files in /var/nginx/ directory. If you wish to launch the container in read-only mode⁠, you need to convert that directory into volume to make it writable:

# To launch container
docker run --name nginx --read-only -v /var/nginx ... ficusio/openresty

# To remove container and its volume
docker rm -v nginx

See this PR⁠ for background.

⁠ONBUILD hook

This image uses ONBUILD hook⁠ that automatically copies all files and subdirectories from the nginx/ directory located at the root of Docker build context (i.e. next to your Dockerfile) into /opt/openresty/nginx/. The minimal configuration needed to get NginX running is the following:

project_root/
 ├ nginx/ # all subdirs/files will be copied to /opt/openresty/nginx/
 |  └ conf/
 |     └ nginx.conf # your NginX configuration file
 └ Dockerfile

Dockerfile:

FROM ficusio/openresty:latest
EXPOSE 8080

Check the sample application⁠ for more useful example.

⁠Command-line parameters

NginX is launched with the nginx -g 'daemon off; error_log /dev/stderr info;' command. This means that you should not specify the daemon directive in your nginx.conf file, because it will lead to NginX config check error (duplicate directive).

No-daemon mode is needed to allow host OS' service manager, like systemd, or Docker itself⁠ to detect that NginX has exited and restart the container. Otherwise in-container service manager would be required.

Error log is redirected to stderr to simplify debugging and log collection with Docker logging drivers⁠ or tools like logspout⁠.

If you wish to run it with different command-line options, you can add CMD directive to your Dockerfile. It will override the command provided in this image. Another option is to pass a command to docker run directly:

$ docker run --rm -it --name test ficusio/openresty bash
root@06823698db68:/opt/openresty/nginx $ ls -l
total 12
drwxr-xr-x    2 root     root          4096 Feb  1 14:48 conf
drwxr-xr-x    2 root     root          4096 Feb  1 14:48 html
drwxr-xr-x    2 root     root          4096 Feb  1 14:48 sbin

⁠Usage during development

To avoid rebuilding your Docker image after each modification of Lua code or NginX config, you can add a simple script that mounts config/content directories to appropriate locations and starts NginX:

#!/usr/bin/env bash

exec docker run --rm -it \
  --name my-app-dev \
  -v "$(pwd)/nginx/conf":/opt/openresty/nginx/conf \
  -v "$(pwd)/nginx/lualib":/opt/openresty/nginx/lualib \
  -p 8080:8080 \
  ficusio/openresty:debian "$@"

# you may add more -v options to mount another directories, e.g. nginx/html/

# do not do -v "$(pwd)/nginx":/opt/openresty/nginx because it will hide
# the NginX binary located at /opt/openresty/nginx/sbin/nginx

Place it next to your Dockerfile, make executable and use during development. You may also want to temporarily disable Lua code cache⁠ to allow testing code modifications without re-starting NginX.