added more docs and examples

Author: fabiocicerchia

README.md

@@ -48,6 +48,19 @@ Lua is a lightweight, high-level, multi-paradigm programming language designed p
 
 > [wikipedia.org/wiki/Lua](https://en.wikipedia.org/wiki/Lua_(programming_language))
 
+## Why this repo and not OpenResty?
+
+| | nginx-lua | OpenResty |
+|--|--|--|
+| nginx latest version | `1.19.3` | `1.17.x` (last tested: `1.17.8`) |
+| Alpine supported | ✅ | ✅ |
+| Amazon supported | ✅ | ✅ |
+| CentOS supported | ✅ | ✅ |
+| Debian supported | ✅ | ✅ |
+| Fedora supported | ✅ | ❌ |
+| Ubuntu supported | ✅ | ✅ |
+| Windows supported | ❌ | ✅ |
+
 ## Features
 
 - Support for Lua.
@@ -62,35 +75,37 @@ Lua is a lightweight, high-level, multi-paradigm programming language designed p
 
 ## 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.
+> 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
 
 ```console
-$ docker run --name some-nginx -v /some/content:/usr/share/nginx/html:ro -d nginx
+$ docker run --name some-nginx -v /some/content:/usr/share/nginx/html:ro -d fabiocicerchia/nginx-lua
 ```
 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):
 ```dockerfile
-FROM nginx
+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:
@@ -108,18 +123,18 @@ Then you can hit `http://localhost:8080` or `http://host-ip:8080` in your browse
 ### Complex configuration
 
 ```console
-$ docker run --name my-custom-nginx-container -v /host/path/nginx.conf:/etc/nginx/nginx.conf:ro -d nginx
+$ docker run --name my-custom-nginx-container -v /host/path/nginx.conf:/etc/nginx/nginx.conf:ro -d fabiocicerchia/nginx-lua
 ```
 For information on the syntax of the nginx configuration files, see [the official documentation](http://nginx.org/en/docs/) (specifically the [Beginner's Guide](http://nginx.org/en/docs/beginners_guide.html#conf_structure)).
 If you wish to adapt the default configuration, use something like the following to copy it from a running nginx container:
 ```console
-$ docker run --name tmp-nginx-container -d nginx
+$ docker run --name tmp-nginx-container -d fabiocicerchia/nginx-lua
 $ docker cp tmp-nginx-container:/etc/nginx/nginx.conf /host/path/nginx.conf
 $ docker rm -f tmp-nginx-container
 ```
 This can also be accomplished more cleanly using a simple `Dockerfile` (in `/host/path/`):
 ```dockerfile
-FROM nginx
+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)!
@@ -133,7 +148,7 @@ Out-of-the-box, nginx doesn't support environment variables inside most configur
 Here is an example using docker-compose.yml:
 ```yaml
 web:
-  image: nginx
+  image: fabiocicerchia/nginx-lua
   volumes:
    - ./templates:/etc/nginx/templates
   ports:
@@ -164,15 +179,15 @@ This behavior can be changed via the following environment variables:
 
 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:
 ```console
-$ docker run -d -p 80:80 --read-only -v $(pwd)/nginx-cache:/var/cache/nginx -v $(pwd)/nginx-pid:/var/run nginx
+$ docker run -d -p 80:80 --read-only -v $(pwd)/nginx-cache:/var/cache/nginx -v $(pwd)/nginx-pid:/var/run fabiocicerchia/nginx-lua
 ```
 If you have a more advanced configuration that requires nginx to write to other locations, simply add more volume mounts to those locations.
 
 ### 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`:
 ```console
-$ docker run -d -e NGINX_ENTRYPOINT_QUIET_LOGS=1 nginx
+$ docker run -d -e NGINX_ENTRYPOINT_QUIET_LOGS=1 fabiocicerchia/nginx-lua
 ```
 
 ### User and group id
@@ -375,6 +390,20 @@ $ docker build \
   -f $DOCKERFILE .
 ```
 
+## 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](#compiled-version-details).
+
+```console
+$ 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:

docs/examples/docker-compose.md

@@ -0,0 +1,11 @@
+```yaml
+web:
+  image: fabiocicerchia/ginx-lua
+  volumes:
+   - ./templates:/etc/nginx/templates
+  ports:
+   - "8080:80"
+  environment:
+   - NGINX_HOST=foobar.com
+   - NGINX_PORT=80
+```

docs/examples/headers-more-nginx-module.md

@@ -0,0 +1,33 @@
+```lua
+# set the Server output header
+more_set_headers 'Server: my-server';
+
+# set and clear output headers
+location /bar {
+    more_set_headers 'X-MyHeader: blah' 'X-MyHeader2: foo';
+    more_set_headers -t 'text/plain text/css' 'Content-Type: text/foo';
+    more_set_headers -s '400 404 500 503' -s 413 'Foo: Bar';
+    more_clear_headers 'Content-Type';
+
+    # your proxy_pass/memcached_pass/or any other config goes here...
+}
+
+# set output headers
+location /type {
+    more_set_headers 'Content-Type: text/plain';
+    # ...
+}
+
+# set input headers
+location /foo {
+    set $my_host 'my dog';
+    more_set_input_headers 'Host: $my_host';
+    more_set_input_headers -t 'text/plain' 'X-Foo: bah';
+
+    # now $host and $http_host have their new values...
+    # ...
+}
+
+# replace input header X-Foo *only* if it already exists
+more_set_input_headers -r 'X-Foo: howdy';
+```

docs/examples/lua-nginx-module.md

@@ -0,0 +1,114 @@
+```nginx
+ # set search paths for pure Lua external libraries (';;' is the default path):
+ lua_package_path '/foo/bar/?.lua;/blah/?.lua;;';
+
+ # set search paths for Lua external libraries written in C (can also use ';;'):
+ lua_package_cpath '/bar/baz/?.so;/blah/blah/?.so;;';
+
+ server {
+     location /lua_content {
+         # MIME type determined by default_type:
+         default_type 'text/plain';
+
+         content_by_lua_block {
+             ngx.say('Hello,world!')
+         }
+     }
+
+     location /nginx_var {
+         # MIME type determined by default_type:
+         default_type 'text/plain';
+
+         # try access /nginx_var?a=hello,world
+         content_by_lua_block {
+             ngx.say(ngx.var.arg_a)
+         }
+     }
+
+     location = /request_body {
+         client_max_body_size 50k;
+         client_body_buffer_size 50k;
+
+         content_by_lua_block {
+             ngx.req.read_body()  -- explicitly read the req body
+             local data = ngx.req.get_body_data()
+             if data then
+                 ngx.say("body data:")
+                 ngx.print(data)
+                 return
+             end
+
+             -- body may get buffered in a temp file:
+             local file = ngx.req.get_body_file()
+             if file then
+                 ngx.say("body is in file ", file)
+             else
+                 ngx.say("no body found")
+             end
+         }
+     }
+
+     # transparent non-blocking I/O in Lua via subrequests
+     # (well, a better way is to use cosockets)
+     location = /lua {
+         # MIME type determined by default_type:
+         default_type 'text/plain';
+
+         content_by_lua_block {
+             local res = ngx.location.capture("/some_other_location")
+             if res then
+                 ngx.say("status: ", res.status)
+                 ngx.say("body:")
+                 ngx.print(res.body)
+             end
+         }
+     }
+
+     location = /foo {
+         rewrite_by_lua_block {
+             res = ngx.location.capture("/memc",
+                 { args = { cmd = "incr", key = ngx.var.uri } }
+             )
+         }
+
+         proxy_pass http://blah.blah.com;
+     }
+
+     location = /mixed {
+         rewrite_by_lua_file /path/to/rewrite.lua;
+         access_by_lua_file /path/to/access.lua;
+         content_by_lua_file /path/to/content.lua;
+     }
+
+     # use nginx var in code path
+     # CAUTION: contents in nginx var must be carefully filtered,
+     # otherwise there'll be great security risk!
+     location ~ ^/app/([-_a-zA-Z0-9/]+) {
+         set $path $1;
+         content_by_lua_file /path/to/lua/app/root/$path.lua;
+     }
+
+     location / {
+        client_max_body_size 100k;
+        client_body_buffer_size 100k;
+
+        access_by_lua_block {
+            -- check the client IP address is in our black list
+            if ngx.var.remote_addr == "132.5.72.3" then
+                ngx.exit(ngx.HTTP_FORBIDDEN)
+            end
+
+            -- check if the URI contains bad words
+            if ngx.var.uri and
+                   string.match(ngx.var.request_body, "evil")
+            then
+                return ngx.redirect("/terms_of_use.html")
+            end
+
+            -- tests passed
+        }
+
+        # proxy_pass/fastcgi_pass/etc settings
+     }
+ }
+```

docs/examples/lua-resty-cookie.md

@@ -0,0 +1,56 @@
+```lua
+    lua_package_path "/path/to/lua-resty-cookie/lib/?.lua;;";
+
+    server {
+        location /test {
+            content_by_lua '
+                local ck = require "resty.cookie"
+                local cookie, err = ck:new()
+                if not cookie then
+                    ngx.log(ngx.ERR, err)
+                    return
+                end
+
+                -- get single cookie
+                local field, err = cookie:get("lang")
+                if not field then
+                    ngx.log(ngx.ERR, err)
+                    return
+                end
+                ngx.say("lang", " => ", field)
+
+                -- get all cookies
+                local fields, err = cookie:get_all()
+                if not fields then
+                    ngx.log(ngx.ERR, err)
+                    return
+                end
+
+                for k, v in pairs(fields) do
+                    ngx.say(k, " => ", v)
+                end
+
+                -- set one cookie
+                local ok, err = cookie:set({
+                    key = "Name", value = "Bob", path = "/",
+                    domain = "example.com", secure = true, httponly = true,
+                    expires = "Wed, 09 Jun 2021 10:18:14 GMT", max_age = 50,
+                    samesite = "Strict", extension = "a4334aebaec"
+                })
+                if not ok then
+                    ngx.log(ngx.ERR, err)
+                    return
+                end
+
+                -- set another cookie, both cookies will appear in HTTP response
+                local ok, err = cookie:set({
+                    key = "Age", value = "20",
+                })
+                if not ok then
+                    ngx.log(ngx.ERR, err)
+                    return
+                end
+            ';
+        }
+    }
+```