Nginx Gateway

A tiny, flexable, configurable Nginx Gateway (reverse proxy) Docker image based on alpine image.

Features

• Enable HTTPS and OCSP Stapling with Let’s Encrypt.
• Automatically register Let’s Encrypt certificate for new domain and update certificates via acme.sh.
• Support to display your custom error pages randomly.
• Support to load and execute Lua codes.
• Support to proxy HTTP and TCP stream.
• Make individual configuration for every domain to serve static files or to proxy the backend servers.
• Support to create multiple pod replicas in k8s.
• Support access log rotation, e.g. access_2018-04-26.log.
• Support authentication with OpenID (via lua-resty-openidc) and to add client IPs to the non-auth whitelist.
• Enable building image with GeoIp2 or not.
• Integrated with Gixy to analyze Nginx configuration to prevent security misconfiguration and automate flaw detection.

How to use?

Image version

The image version is formated as <nginx version>-r<revision number>[p<patch number>], e.g. 1.11.2-r1, 1.11.2-r1p1, 1.11.2-r2 etc.

Build image

Run the following commands in the root directory of this git repository:

IMAGE_VERSION=1.15.12-r1
IMAGE_NAME=flytreeleft/nginx-gateway:${IMAGE_VERSION}

docker build --rm -t ${IMAGE_NAME} .

If you want to enable GeoIp2, just set the build argument enable_geoip to true:

IMAGE_VERSION=1.15.12-r1
IMAGE_NAME=flytreeleft/nginx-gateway-with-geoip:${IMAGE_VERSION}

docker build --rm --build-arg enable_geoip=true -t ${IMAGE_NAME} .

Note: You can run docker pull flytreeleft/nginx-gateway or docker pull flytreeleft/nginx-gateway-with-geoip to get the latest image from the Docker Hub.

Create and run

DCR_IMAGE_VERSION=1.15.12-r1

DCR_NAME=nginx-gateway
DCR_IMAGE=flytreeleft/nginx-gateway:${DCR_IMAGE_VERSION}

DCR_VOLUME=/var/lib/nginx-gateway

DEBUG=false
ULIMIT=655360
ENABLE_CUSTOM_ERROR_PAGE=true
CERT_EMAIL=nobody@example.com

ulimit -n ${ULIMIT}
docker run -d --name ${DCR_NAME} \
                --restart always \
                --network host \
                --ulimit nofile=${ULIMIT} \
                -p 443:443 -p 80:80 \
                -e DEBUG=${DEBUG} \
                -e CERT_EMAIL=${CERT_EMAIL} \
                -e ENABLE_CUSTOM_ERROR_PAGE=${ENABLE_CUSTOM_ERROR_PAGE} \
                -e DISABLE_CERTBOT=false \
                -e DISABLE_GIXY=false \
                -v /usr/share/zoneinfo:/usr/share/zoneinfo:ro \
                -v /etc/localtime:/etc/localtime:ro \
                -v ${DCR_VOLUME}/logs:/var/log/nginx/sites \
                -v ${DCR_VOLUME}/letsencrypt:/etc/letsencrypt \
                -v ${DCR_VOLUME}/vhost.d:/etc/nginx/vhost.d \
                -v ${DCR_VOLUME}/stream.d:/etc/nginx/stream.d \
                -v ${DCR_VOLUME}/epage.d:/etc/nginx/epage.d \
                ${DCR_IMAGE}

Note:

• If you want to use your error pages, just set ENABLE_CUSTOM_ERROR_PAGE to false, and put your configuration (e.g. config/error-pages/01_default.conf) and error pages to ${STORAGE}/epage.d.
• Mapping /usr/share/zoneinfo and /etc/localtime from the host machine to make sure the container use the same Time Zone with the host.
• The access and error log will be put in the directory /var/log/nginx/sites/{domain}. The access log file will be named as access_{date}.log (e.g. access_2018-04-26.log), and the error log will be named as error.log.
• Set DISABLE_CERTBOT to true if you want to disable certbot to register or update Let’s Encrypt certificate automatically. If certbot is disabled, you can run $ docker exec -it nginx-gateway sh -c '/usr/bin/build-certs && /usr/sbin/nginx -s reload' to update Let’s Encrypt certificate manually.
• Set DISABLE_GIXY to true if you don't want to run Gixy to check Nginx configuration files when they are changed. Otherwise, you can run docker logs --tail 100 ${DCR_NAME} to check the detection results.

How to configure your site?

There are some examples in examples/vhost.d for different needs.

In config/10_default.conf, all HTTP requests will be redirected to HTTPS, so you just need to listen on 443 and configure for you HTTPS site which is like the following codes:

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name <your-domain>;

    # Note: The additional configuration files (for ssl, log, etc.) which are generated automatically
    # will be put into the fixed location as '/etc/nginx/vhost.d/<your-domain>',
    # so do not change it.
    include /etc/nginx/vhost.d/<your-domain>/*.conf;

    location / {
        # Avoid to get address resolve error when starting
        set $target http://<proxy to backend>:80;
        proxy_pass  $target;
    }
}

Also, you can put the global and default settings in one file (e.g. vhost.d/00_default.conf), just make sure it will be loaded before the other site configuration files. Here are some usefull configurations:

resolver 8.8.8.8 valid=300s;
resolver_timeout 5s;

# Websocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# Force to change the redirect url's scheme to https
proxy_redirect   http:// $scheme://;
proxy_redirect     / /;

For other needs, see details in:

• Enable upload big files to your site
• The Nexus3 repository sites for Docker images and the library packages of Maven, NPM, etc.
• Proxy the static files behind the firewall
• Enable the HTTP Basic Authentication or OpenID
• Proxy the TCP streams

Thanks

• nginxinc/docker-nginx: The official NGINX Dockerfiles based on alpine image.
• sebble/docker-images/letsencrypt-certbot: Running certbot via crontab.
• nrollr/nginx.conf: NGINX config for SSL with Let's Encrypt certs.
• JrCs/docker-letsencrypt-nginx-proxy-companion: LetsEncrypt companion container for nginx-proxy.
• tmthrgd/nginx-status-text.conf: Nginx status code to message map.
• Using NGINX’s X-Accel with Remote URLs
• How to make an existing caching Nginx proxy use another proxy to bypass a firewall?
• nginx docker container cannot see client ip when using '--iptables=false' option
• Log rotation directly within Nginx configuration file: Using variables in access_log directives to rotate access log. Note: embed variables can not be used in error_log directives.
• Log rotation directly within Nginx configuration file: map instead of if: Using map directives instead of if for rotating access log.
• zmartzone/lua-resty-openidc: Give a way to enable OpenID authentication for Nginx.
• Gixy: A tool to analyze Nginx configuration to prevent security misconfiguration.

Reference

• Nginx ssl_stapling
• Nginx alias: Used to change the directory path of the request file.
• Nginx sub_filter: Filter and modify the response body.
• Nginx error_page: Define the error page or URI.
• Nginx random_index: Picks a random file in a directory to serve as an index file.
• Nginx proxy_intercept_errors: Intercept proxy errors and redirected them to nginx for processing with the error_page directive.
• Nginx proxy_hide_header: Hide the headers from the response of a proxied server to a client.
• Nginx variables
• Nginx log_format&access_log