bfren/nginx-proxy
Nginx proxy image based on Alpine Linux, with automated SSL Lets Encrypt certificate requests.
10K+
bfren/nginx-proxy repository overview
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
Copyright
Copyright (c) 2020-2024 bfren (unless otherwise stated)
Tag summary
Content type
Image
Digest
sha256:37ae94a48…
Size
12.5 MB
Last updated
2 months ago
docker pull bfren/nginx-proxy:7.1.6-dev