digitalist/nginx repository overview

Nginx container, built on Wolfi.

⁠Modules

Examples go in a server/location block in /etc/nginx/conf.d/default.conf unless noted. The stock modules built as =dynamic (xslt, image_filter, geoip, perl, mail, stream) are not shipped in the image. Run docker run --rm <image> nginx -V to see the build flags.

⁠Added modules

⁠geoip2 (ngx_http_geoip2_module)

Loaded in nginx.conf, with the GeoLite2 country database at /usr/share/geoip/GeoLite2-Country.mmdb. $geoip2_data_country_code is already defined (looked up from X-Forwarded-For, defaulting to SE) and goes into the main_geo access log.

location /eu/ {
    if ($geoip2_data_country_code !~ ^(SE|NO|DK|FI)$) { return 403; }
}
add_header X-Country $geoip2_data_country_code always;

⁠headers-more (ngx_http_headers_more_filter_module)

To use it, add this line to the top of your own nginx.conf:

load_module /usr/lib/nginx/modules/ngx_http_headers_more_filter_module.so;

more_set_headers   "Server: web";
more_clear_headers X-Powered-By;

⁠Built-in modules

⁠Sub filter (http_sub_module)

location / {
    sub_filter '</head>' '<script>console.log("foo")</script></head>';
    sub_filter_once on;
    sub_filter_types text/html;
    try_files $uri $uri/ /index.html;
}

With this, a simple console log is done on every request.

⁠Addition (http_addition_module)

Adds the output of other locations before and after the response body.

location /banner/ {
    add_before_body /_header.html;
    add_after_body  /_footer.html;
}

⁠Real IP (http_realip_module)

Replaces the client address with the one sent by a trusted proxy or load balancer.

set_real_ip_from  10.0.0.0/8;
real_ip_header    X-Forwarded-For;
real_ip_recursive on;

⁠HTTP/2 (http_v2_module)

listen 80;
http2 on;

⁠SSL (http_ssl_module)

TLS needs a cert, which the image doesn't include. Mount one and use a port above 1024, because the container runs as non-root.

listen 8443 ssl;
ssl_certificate     /etc/nginx/certs/tls.crt;
ssl_certificate_key /etc/nginx/certs/tls.key;

⁠Auth request (http_auth_request_module)

Authorizes each request with a subrequest: a 2xx response allows it, and a 401 or 403 denies it.

location /private/ {
    auth_request     /auth;
    auth_request_set $user $upstream_http_x_user;
}
location = /auth {
    internal;
    proxy_pass              http://backend/verify;
    proxy_pass_request_body off;
    proxy_set_header        Content-Length "";
    proxy_set_header        X-Original-URI $request_uri;
}

⁠Secure link (http_secure_link_module)

Expiring signed URLs: /dl/file.zip?md5=<hash>&expires=<unix ts>.

location /dl/ {
    secure_link     $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri secret";
    if ($secure_link = "")  { return 403; }
    if ($secure_link = "0") { return 410; }
}

Generate the hash with: echo -n '2147483647/dl/file.zip secret' | openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =

⁠Gzip static (http_gzip_static_module)

Serves a precompressed file.gz when it sits next to file.

location /assets/ { gzip_static on; }

⁠Gunzip (http_gunzip_module)

Decompresses gzipped responses for clients that don't support gzip.

location /legacy/ { gunzip on; }

⁠Slice (http_slice_module)

Splits large responses into ranges that can be cached separately.

location /big/ {
    slice             1m;
    proxy_cache_key   $uri$is_args$args$slice_range;
    proxy_set_header  Range $slice_range;
    proxy_pass        http://backend;
}

⁠MP4 / FLV (http_mp4_module, http_flv_module)

Pseudo-streaming with seeking (?start=30).

location /video/ { mp4; mp4_buffer_size 1m; mp4_max_buffer_size 5m; }
location ~ \.flv$ { flv; }

⁠Random index (http_random_index_module)

Serves a random file from the directory for requests that end in /.

location /random/ { random_index on; }

⁠Stub status (http_stub_status_module)

Basic connection and request counters.

location = /nginx_status {
    stub_status;
    allow 127.0.0.1;
    deny  all;
}

⁠Degradation (http_degradation_module)

Returns an error instead of serving when memory is low. degradation goes in the http block.

# http {}
degradation sbrk=500m;
# location
location /heavy/ { degrade 204; }

The standard nginx modules (proxy, fastcgi, rewrite, gzip, headers, limit_req, limit_conn, map, geo, split_clients, auth_basic, access, upstream, etc.) are also included.

⁠License

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com⁠.