A tiny, flexable, configurable Nginx gateway (reverse proxy) Docker image
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
config
examples
.gitignore
Dockerfile
README.md
build.sh
run.sh

README.md

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 certbot.
  • 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.11.2-r2
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.11.2-r2
IMAGE_NAME=flytreeleft/nginx-gateway-with-geoip:${IMAGE_VERSION}

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

Create and run

DCR_IMAGE_VERSION=1.11.2-r2

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_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_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:

Thanks

Reference