Docker Nginx Proxy

Docker Repository - bfren ecosystem

Nginx Proxy which uses getssl to automate requesting and renewing SSL certificates via Let's Encrypt. Certificates are checked for renewal every day - the last check can be viewed in the /ssl volume. Also includes NAXSI, a web application firewall.

As of v4, configuration is handled via a JSON file - see ssl-conf-sample.json for an example and ssl-conf-schema.json for the full file definition.

Contents

• Ports
• Volumes
• Environment Variables
• Helper Functions
• Nginx Configuration Helpers
• Licence / Copyright

Ports

For SSL certificate requests to work correctly, ports 80 and 443 need mapping from the host to your proxy container, e.g. adding "0.0.0.0:80:80" to the ports section of your docker compose file.

• 80 (from base image)
• 443

Volumes

Volume	Purpose
/www	From base image.
/sites	Nginx site configuration, auto-generated on first run based on conf.json. After they are generated, you can alter them to suit their needs. Running nginx-regenerate will wipe them all and start again.
/ssl	Contains auto-generated SSL configuration and certificates (for backup purposes). Your conf.json file should be stored in here for auto-configuration (see ssl-conf-sample.json). Certificate update log (update.log) will be created here daily.

Environment Variables

Variable	Values	Description	Default
PROXY_AUTO_PRIMARY	URI	If set (along with PROXY_AUTO_UPSTREAM) SSL config will be generated on first startup.	None
PROXY_AUTO_UPSTREAM	URI	If set (along with PROXY_AUTO_PRIMARY) SSL config will be generated on first startup.	None
PROXY_AUTO_ALIASES	string of URIs	Add aliases to the auto-generated conf.json on first startup.	None
PROXY_AUTO_CUSTOM	0 or 1	Mark the auto-generated SSL config to 'custom' so the Nginx configuration is not regenerated on startup.	0
PROXY_CLEAN_INSTALL	0 or 1	If 1, all Nginx and SSL configuration and certificates will be deleted and regenerated.	0
PROXY_DOMAIN	URI	The base domain of the proxy server - will be used to handle unbound requests.	None - required
PROXY_ENABLE_NAXSI	0 or 1	If 1, NAXSI web application firewall will be enabled for all sites.	0
PROXY_GETSSL_SKIP_HTTP_TOKEN_CHECK	true or false	Set to true to enable getssl's skip HTTP token check.	false
PROXY_HARDEN	0 or 1	If 1, only modern SSL ciphers and protocols will be enabled (some older devices may not be able to access it).	0
PROXY_LETS_ENCRYPT_EMAIL	A valid email address	Used by Lets Encrypt for notification emails.	None - required
PROXY_LETS_ENCRYPT_LIVE	0 or 1	Only set to 1 (to request live certificates) when your config is correct - Lets Encrypt rate limit certificate requests.	0
PROXY_MAINTENANCE_REFRESH_SECONDS	A valid integer	The number of seconds to count down before the maintenance page auto-refreshes.	6
PROXY_SSL_DHPARAM_BITS	A valid integer	The size of your DHPARAM variables - adjust down only if you have limited processing resources.	4096
PROXY_SSL_REDIRECT_TO_CANONICAL	0 or 1	If 1, all requests will be redirected to the primary domain (defined in conf.json).	0
PROXY_UPSTREAM_DNS_RESOLVER	IP address	Upstream DNS resolver - set to Docker's by default.	127.0.0.11

Helper Functions

Function	Arguments	Description
nginx-adduser	0: username, 1: password	Add a user to enable basic HTTP auth.
nginx-regenerate	-a: all domains, -d XXXXXX: only domain XXXXXX, -f: force	Removes non-custom Nginx configuration files (in /sites) and regenerates based on conf.json (with force, removes all).
ssl-cleanup	-m: mode	Removes SSL and Nginx configuration files and directories not defined in conf.json (mode 0 = dry run, 1 = live).
ssl-init	-a: all domains, -d XXXXXX: only domain XXXXXX	Initialises SSL configuration based on conf.json.
ssl-regenerate	-a: all domains, -d XXXXXX: only domain XXXXXX	Removes SSL configuration files (in /ssl/certs) and regenerates based on conf.json.
ssl-regenerate-full	None	Removes SSL configuration files (in /ssl/certs), as well as DH parameters, and regenerates based on conf.json.
ssl-request	-a: all domains, -d XXXXXX: only domain XXXXXX	Requests SSL certificates from Lets Encrypt.
ssl-update	-a: all domains, -d XXXXXX: only domain XXXXXX	Attempts to update SSL certificates manually.

Nginx Configuration Helpers

The image contains a handful of useful Nginx configuration 'helper' files, which you can find in /overlay/etc/nginx/helpers. They all begin with the prefix 'proxy':

Helper	Description
-maintenance.conf	Displays a maintenance page (used when upstream server is returning an error 50x).
-params.conf	Headers commonly required when proxying a site.
-params-websockets.conf	Headers required to use websockets.
-secure-headers.conf	Standard secure headers - see Mozilla SSL Configuration Generator.
-tls1_3-only.conf	If you want to be ultra-secure (and not support older browsers), this will disable all TLS protocols except 1.3.

Licence

MIT

Copyright

Copyright (c) 2020-2023 bfren (unless otherwise stated)