Awesome

Nginx & Lua

Latest Nginx with LUA support based on AlmaLinux, Alpine Linux, Amazon Linux, Debian, Fedora, and Ubuntu.

💗 Support the Project 💗

This project is only maintained by one person, Fabio Cicerchia.
It started as a simple docker image, now it updates automatically periodically and provides support for multiple distro 😎
Maintaining a project is a very time consuming activity, especially when done alone 💪
I really want to make this project better and become super cool 🚀

If you'd like to support this open-source project I'll appreciate any kind of contribution.

Quick reference

• Maintained by: Fabio Cicerchia
• Where to get help: the Docker Community Forums, the Docker Community Slack, or Stack Overflow

Supported tags and respective Dockerfile links

• almalinux, 1-almalinux, 1.27-almalinux, 1.27.3-almalinux, 1-almalinux9.5-20241118, 1.27-almalinux9.5-20241118, 1.27.3-almalinux9.5-20241118
• 1, 1.27, 1.27.3, alpine, latest, 1-alpine, 1.27-alpine, 1.27.3-alpine, 1-alpine3.21.0, 1.27-alpine3.21.0, 1.27.3-alpine3.21.0
• amazonlinux, 1-amazonlinux, 1.27-amazonlinux, 1.27.3-amazonlinux, 1-amazonlinux2023.6.20241212.0, 1.27-amazonlinux2023.6.20241212.0, 1.27.3-amazonlinux2023.6.20241212.0
• debian, 1-debian, 1.27-debian, 1-debian12.8, 1.27.3-debian, 1.27-debian12.8, 1.27.3-debian12.8
• fedora, 1-fedora, 1-fedora41, 1.27-fedora, 1.27-fedora41, 1.27.3-fedora, 1.27.3-fedora41
• ubuntu, 1-ubuntu, 1.27-ubuntu, 1-ubuntu24.04, 1.27.3-ubuntu, 1.27-ubuntu24.04, 1.27.3-ubuntu24.04

Note: The full list of supported/unsupported tags can be found on docs/TAGS.md.

Quick reference (cont.)

• Where to file issues: https://github.com/fabiocicerchia/nginx-lua/issues
• Supported architectures: amd64, arm64
• Published image artifact details: repo-info repo's docs/metadata/ directory (history) (image metadata, transfer size, etc)

What is nginx?

Nginx (pronounced "engine-x") is an open source reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer, HTTP cache, and a web server (origin server). The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

wikipedia.org/wiki/Nginx

What is Lua?

Lua is a lightweight, high-level, multi-paradigm programming language designed primarily for embedded use in applications. Lua is cross-platform, since the interpreter of compiled bytecode is written in ANSI C, and Lua has a relatively simple C API to embed it into applications.

wikipedia.org/wiki/Lua

Why this repo and not OpenResty?

With this project you'll get a fresh nginx + lua version the day after (or even less than a day) of the release of a new nginx version!

¹ Note:

• Between official nginx 1.25.3 (24 Oct 2023) and OpenResty compatibility for 1.25.3.1 (9 Jan 2024) have passed ~3 months, instead fabiocicerchia/nginx-lua took 2 days.
• On previous OpenResty version 1.21.x: the whole mainline 1.23.x has been skipped, while fabiocicerchia/nginx-lua was providing the version.
• On latest version 1.25.x: between the first nginx release (23 May 2023) and the first OpenResty one (9 Jan 2024) have passed ~8 months.

Features

• Support for Lua.
• Minimal size only, minimal layers.
• Same build configure of official nginx image.
• Security checks: Docker Bench Security, Snyk.
• Docker Healthchecks.
• Exposes default ports (80 and 443), easy to extend.
• Support for multiple linux distros: AlmaLinux, Alpine, Amazon, Debian, Fedora, Ubuntu.
• Extra Lua Modules.
• Performance Benchmarks.
• LuaRocks Support.
• NJS Support.

Typical Uses

Just to name a few:

• Mashup'ing and processing outputs of various Nginx upstream outputs (proxy, drizzle, postgres, redis, memcached, and etc) in Lua,
• doing arbitrarily complex access control and security checks in Lua before requests actually reach the upstream backends,
• manipulating response headers in an arbitrary way (by Lua)
• fetching backend information from external storage backends (like redis, memcached, mysql, postgresql) and use that information to choose which upstream backend to access on-the-fly,
• coding up arbitrarily complex web applications in a content handler using synchronous but still non-blocking access to the database backends and other storage,
• doing very complex URL dispatch in Lua at rewrite phase,
• using Lua to implement advanced caching mechanism for Nginx's subrequests and arbitrary locations.

The possibilities are unlimited as the module allows bringing together various elements within Nginx as well as exposing the power of the Lua language to the user. The module provides the full flexibility of scripting while offering performance levels comparable with native C language programs both in terms of CPU time as well as memory footprint thanks to LuaJIT 2.x.

Other scripting language implementations typically struggle to match this performance level.

• https://github.com/openresty/lua-nginx-module#typical-uses

How to use this image

Hosting some simple static content

$ docker run --name some-nginx -v /some/content:/usr/share/nginx/html:ro -d fabiocicerchia/nginx-lua
[...OMITTED...]

Alternatively, a simple Dockerfile can be used to generate a new image that includes the necessary content (which is a much cleaner solution than the bind mount above):

FROM fabiocicerchia/nginx-lua
COPY static-html-directory /usr/share/nginx/html

Place this file in the same directory as your directory of content ("static-html-directory"), run docker build -t some-content-nginx ., then start your container:

$ docker run --name some-nginx -d some-content-nginx
[...OMITTED...]

Exposing external port

$ docker run --name some-nginx -d -p 8080:80 some-content-nginx
[...OMITTED...]

Then you can hit http://localhost:8080 or http://host-ip:8080 in your browser.

Complex configuration

$ docker run --name my-custom-nginx-container -v /host/path/nginx.conf:/etc/nginx/nginx.conf:ro -d fabiocicerchia/nginx-lua
[...OMITTED...]

For information on the syntax of the nginx configuration files, see the official documentation (specifically the Beginner's Guide). If you wish to adapt the default configuration, use something like the following to copy it from a running nginx container:

$ docker run --name tmp-nginx-container -d fabiocicerchia/nginx-lua
[...OMITTED...]
$ docker cp tmp-nginx-container:/etc/nginx/nginx.conf /host/path/nginx.conf
[...OMITTED...]
$ docker rm -f tmp-nginx-container
[...OMITTED...]

This can also be accomplished more cleanly using a simple Dockerfile (in /host/path/):

FROM fabiocicerchia/nginx-lua
COPY nginx.conf /etc/nginx/nginx.conf

If you add a custom CMD in the Dockerfile, be sure to include -g daemon off; in the CMD in order for nginx to stay in the foreground, so that Docker can track the process properly (otherwise your container will stop immediately after starting)! Then build the image with docker build -t custom-nginx . and run it as follows:

$ docker run --name my-custom-nginx-container -d custom-nginx
[...OMITTED...]

Using environment variables in nginx configuration (new in 1.19)

Out-of-the-box, nginx doesn't support environment variables inside most configuration blocks. But this image has a function, which will extract environment variables before nginx starts. Here is an example using docker-compose.yml:

web:
  image: fabiocicerchia/nginx-lua
  volumes:
    - ./templates:/etc/nginx/templates
  ports:
    - "8080:80"
  environment:
    - NGINX_HOST=foobar.com
    - NGINX_PORT=80

By default, this function reads template files in /etc/nginx/templates/*.template and outputs the result of executing envsubst to /etc/nginx/conf.d. So if you place templates/default.conf.template file, which contains variable references like this:

listen       ${NGINX_PORT};

outputs to /etc/nginx/conf.d/default.conf like this:

listen       80;

This behavior can be changed via the following environment variables:

• NGINX_ENVSUBST_TEMPLATE_DIR
  • A directory which contains template files (default: /etc/nginx/templates)
  • When this directory doesn't exist, this function will do nothing about template processing.
• NGINX_ENVSUBST_TEMPLATE_SUFFIX
  • A suffix of template files (default: .template)
  • This function only processes the files whose name ends with this suffix.
• NGINX_ENVSUBST_OUTPUT_DIR
  • A directory where the result of executing envsubst is output (default: /etc/nginx/conf.d)
  • The output filename is the template filename with the suffix removed.
    • ex.) /etc/nginx/templates/default.conf.template will be output with the filename /etc/nginx/conf.d/default.conf.
  • This directory must be writable by the user running a container.

Running nginx in read-only mode

To run nginx in read-only mode, you will need to mount a Docker volume to every location where nginx writes information. The default nginx configuration requires write access to /var/cache and /var/run. This can be easily accomplished by running nginx as follows:

$ docker run -d -p 80:80 --read-only -v $(pwd)/nginx-cache:/var/cache/nginx -v $(pwd)/nginx-pid:/var/run fabiocicerchia/nginx-lua
[...OMITTED...]

If you have a more advanced configuration that requires nginx to write to other locations, simply add more volume mounts to those locations.

Running nginx in debug mode

Images since version 1.19.3 come with nginx-debug binary that produces verbose output when using higher log levels. It can be used with simple CMD substitution:

$ docker run --name my-nginx -v /host/path/nginx.conf:/etc/nginx/nginx.conf:ro -d fabiocicerchia/nginx-lua nginx-debug -g 'daemon off;'
[...OMITTED...]

Similar configuration in docker-compose.yml may look like this:

web:
  image: fabiocicerchia/nginx-lua
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro
  command: [nginx-debug, '-g', 'daemon off;']

Entrypoint quiet logs

Since version 1.19.0, a verbose entrypoint was added. It provides information on what's happening during container startup. You can silence this output by setting environment variable NGINX_ENTRYPOINT_QUIET_LOGS:

$ docker run -d -e NGINX_ENTRYPOINT_QUIET_LOGS=1 fabiocicerchia/nginx-lua
[...OMITTED...]

User and group id

Since 1.17.0, both alpine- and debian-based images variants use the same user and group ids to drop the privileges for worker processes:

$ id
uid=101(nginx) gid=101(nginx) groups=101(nginx)

Running nginx as a non-root user

It is possible to run the image as a less privileged arbitrary UID/GID. This, however, requires modification of nginx configuration to use directories writeable by that specific UID/GID pair:

$ docker run -d -v $PWD/nginx.conf:/etc/nginx/nginx.conf fabiocicerchia/nginx-lua
[...OMITTED...]

where nginx.conf in the current directory should have the following directives re-defined:

pid        /tmp/nginx.pid;

And in the http context:

http {
    client_body_temp_path /tmp/client_temp;
    proxy_temp_path       /tmp/proxy_temp_path;
    fastcgi_temp_path     /tmp/fastcgi_temp;
    uwsgi_temp_path       /tmp/uwsgi_temp;
    scgi_temp_path        /tmp/scgi_temp;
...
}

Specs

• nginx

• Supported OS

  • AlmaLinux (~620MB)
  • Alpine Linux (~90MB)
  • Amazon Linux (~380MB)
  • Debian (~330MB)
  • Fedora (~680MB)
  • Ubuntu (~280MB)

• OpenResty's Branch of LuaJIT 2

  • Currently based on Lua 5.1.4

• Embed the Power of Lua into NGINX HTTP servers

• New FFI-based API for lua-nginx-module

• Lua-land LRU Cache based on LuaJIT FFI

• Nginx Development Kit

• LuaRocks

• <details><summary>Additional Modules</summary>
  • geoip2
  • ngx_http_addition_module
  • ngx_http_auth_request_module
  • ngx_http_dav_module
  • ngx_http_flv_module
  • ngx_http_gunzip_module
  • ngx_http_gzip_static_module
  • ngx_http_mp4_module
  • ngx_http_random_index_module
  • ngx_http_realip_module
  • ngx_http_secure_link_module
  • ngx_http_slice_module
  • ngx_http_ssl_module
  • ngx_http_stub_status_module
  • ngx_http_sub_module
  • ngx_http_v2_module
  • ngx_mail
  • ngx_mail_ssl_module
  • ngx_stream
  • ngx_stream_realip_module
  • ngx_stream_ssl_module
  • ngx_stream_ssl_preread_module
  • njs
  • headers-more-nginx-module
  • lua-resty-balancer
  • lua-resty-cookie
  • lua-resty-dns
  • lua-resty-limit-traffic
  • lua-resty-lock
  • lua-resty-lrucache
  • lua-resty-memcached
  • lua-resty-mysql
  • lua-resty-redis
  • lua-resty-shell
  • lua-resty-signal
  • lua-resty-string
  • lua-resty-upload
  • lua-resty-upstream-healthcheck
  • lua-resty-websocket
  • lua-tablepool
  • lua-upstream-nginx-module
  • nginx-lua-prometheus
  • set-misc-nginx-module
  • stream-lua-nginx-module
  </details>

Compiled Version Details

nginx version: nginx/1.25.3
built by gcc 13.2.1 20231014 (Alpine 13.2.1_git20231014)
built with OpenSSL 3.1.4 24 Oct 2023
TLS SNI support enabled
configure arguments: --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --modules-path=/usr/lib/nginx/modules --conf-path=/etc/nginx/nginx.conf --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --pid-path=/var/run/nginx.pid --lock-path=/var/run/nginx.lock --http-client-body-temp-path=/var/cache/nginx/client_temp --http-proxy-temp-path=/var/cache/nginx/proxy_temp --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp --http-scgi-temp-path=/var/cache/nginx/scgi_temp --with-perl_modules_path=/usr/lib/perl5/vendor_perl --user=nginx --group=nginx --with-compat --with-file-aio --with-threads --with-http_addition_module --with-http_auth_request_module --with-http_dav_module --with-http_flv_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_mp4_module --with-http_random_index_module --with-http_realip_module --with-http_secure_link_module --with-http_slice_module --with-http_ssl_module --with-http_stub_status_module --with-http_sub_module --with-http_v2_module --with-mail --with-mail_ssl_module --with-stream --with-stream_realip_module --with-stream_ssl_module --with-stream_ssl_preread_module --add-module=/headers-more-nginx-module-0.36 --add-module=/lua-nginx-module-0.10.25 --add-module=/lua-upstream-nginx-module-0.07 --add-module=/ngx_devel_kit-0.3.3 --add-module=/ngx_http_geoip2_module-3.4 --add-module=/njs-0.8.2/nginx --add-module=/set-misc-nginx-module-0.33 --add-module=/stream-lua-nginx-module-0.0.13 --with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2 -fPIC' --with-ld-opt='-Wl,-rpath,/usr/local/lib -Wl,-z,relro -Wl,-z,now -Wl,--as-needed -pie'

The following are the available build-time options. They can be set using the --build-arg CLI argument.

These built-from-source flavors include the following modules by default, but one can easily increase or decrease that with the custom build options above:

• file-aio
• threads
• http_addition_module
• http_auth_request_module
• http_dav_module
• http_flv_module
• http_gunzip_module
• http_gzip_static_module
• http_mp4_module
• http_random_index_module
• http_realip_module
• http_secure_link_module
• http_slice_module
• http_ssl_module
• http_stub_status_module
• http_sub_module
• http_v2_module
• mail
• mail_ssl_module
• stream
• stream_realip_module
• stream_ssl_module
• stream_ssl_preread_module

Notes

• The SIGQUIT signal will be sent to nginx to stop this container, to give it an opportunity to stop gracefully (i.e, finish processing active connections). The Docker default is SIGTERM, which immediately terminates active connections. Note that if your configuration listens on UNIX domain sockets, this means that you'll need to manually remove the socket file upon shutdown, due to nginx bug #753.

Run Container

$ docker run -it --rm -p 80:80 \
  --health-cmd='curl --fail http://example.com || exit 1' \
  --health-interval=30s \
  --health-timeout=3s \
  fabiocicerchia/nginx-lua:latest

Image Variants

fabiocicerchia/nginx-lua:<version>

The default Nginx + Lua + extra lua modules image. Uses Alpine Linux for base image.

fabiocicerchia/nginx-lua:<version>-<distro>

Provides Nginx + Lua + extra lua modules. Uses AlmaLinux, Alpine Linux, Amazon Linux, Debian, Fedora, Ubuntu for base image.

fabiocicerchia/nginx-lua:<version>-<distro><version>

Provides Nginx + Lua + extra lua modules. Uses pinned version for AlmaLinux, Alpine Linux, Amazon Linux, Debian, Fedora, Ubuntu for base image.

Custom Builds

If you need to extend the functionality of the existing image, you could build your own version using the following command. For the list of values do refer to the relative section.

$ docker build \
  --build-arg NGINX_BUILD_CONFIG=... \ # nginx build flags
  --build-arg BUILD_DEPS=... \ # packages needed for building phase
  --build-arg NGINX_BUILD_DEPS=... \ # packages needed for building phase by nginx
  --build-arg PKG_DEPS=... \ # packages available in final image
  -f $DOCKERFILE .

Image Labels

The image builds are labeled with various information. Here's an example of printing the labels using jq:

$ docker pull fabiocicerchia/nginx-lua:1-alpine
$ docker inspect fabiocicerchia/nginx-lua:1-alpine | jq '.[].Config.Labels'
{
  "image.target.arch": "amd64",
  "image.target.os": "",
  "image.target.platform": "",
  "maintainer": "Fabio Cicerchia <info@fabiocicerchia.it>",
  "org.label-schema.build-date": "2024-01-17T00:00:00Z",
  "org.label-schema.description": "Nginx 1.25.3 with Lua support based on alpine (amd64) 3.19.0.",
  "org.label-schema.docker.cmd": "docker run -p 80:80 -d fabiocicerchia/nginx-lua:1.25.3-alpine3.19.0",
  "org.label-schema.name": "fabiocicerchia/nginx-lua",
  "org.label-schema.schema-version": "1.0",
  "org.label-schema.url": "https://github.com/fabiocicerchia/nginx-lua",
  "org.label-schema.vcs-ref": "b0482b3",
  "org.label-schema.vcs-url": "https://github.com/fabiocicerchia/nginx-lua",
  "org.label-schema.version": "1.25.3-alpine3.19.0",
  "versions.geoip": "3.4",
  "versions.headers-more-nginx-module": "0.36",
  "versions.lua-nginx-module": "0.10.25",
  "versions.lua-resty-balancer": "0.05",
  "versions.lua-resty-cookie": "f418d77082eaef48331302e84330488fdc810ef4",
  "versions.lua-resty-core": "0.1.27",
  "versions.lua-resty-dns": "0.23",
  "versions.lua-resty-limit-traffic": "0.09",
  "versions.lua-resty-lock": "0.09",
  "versions.lua-resty-lrucache": "0.13",
  "versions.lua-resty-memcached": "0.17",
  "versions.lua-resty-mysql": "0.26",
  "versions.lua-resty-redis": "0.30",
  "versions.lua-resty-shell": "0.03",
  "versions.lua-resty-signal": "0.03",
  "versions.lua-resty-string": "0.15",
  "versions.lua-resty-tablepool": "0.03",
  "versions.lua-resty-upload": "0.11",
  "versions.lua-resty-upstream-healthcheck": "0.08",
  "versions.lua-resty-websocket": "0.11",
  "versions.lua-upstream": "0.07",
  "versions.luajit2": "2.1-20231117",
  "versions.luarocks": "3.9.2",
  "versions.nginx": "1.25.3",
  "versions.nginx-lua-prometheus": "0.20230607",
  "versions.ngx_devel_kit": "0.3.3",
  "versions.njs": "0.8.2",
  "versions.os": "3.19.0",
  "versions.set-misc-nginx": "0.33",
  "versions.stream-lua-nginx-module": "0.0.13"
}

Benchmarks

nginx vs nginx-lua vs openresty

More details about the benchark can be found in docs/benchmarks/different_images.

nginx-lua different distro

More details about the benchark can be found in docs/benchmarks/distros.

Extras

Extract of openresty/lua-nginx-module under BSD license.

• LUA Nginx Module - Known Issues
• LUA Nginx Module - Directives
• Nginx API for Lua

Examples

Virtual Host

server {
  server_name localhost;

  location /lua_content {
    default_type 'text/plain';

    content_by_lua_block {
      ngx.say('Hello world!')
    }
  }
}

Docker Compose

version: '3.7'
services:
  nginx-lua:
    image: fabiocicerchia/nginx-lua:latest
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /path/to/docroot:/var/www/html
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    healthcheck:
      test: ['CMD', 'curl --fail http://localhost/ || exit 1']
      interval: 30s
      timeout: 3s
      retries: 3

More examples are available in the directory docs/examples

Contributing

A dedicated section is available to know how to contribute to this project.

License

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

• Nginx License
• Lua License
• LuaJIT License
• OpenResty License

fabiocicerchia/nginx-lua

MIT License

Copyright (c) 2020-2023 Fabio Cicerchia info@fabiocicerchia.it

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.