nfrastack/container-nginx

About

This will build a container for Nginx, for serving websites or proxying data.

Tracks Mainline release channel
Many options configurable including compression, performance, status reporting
Ability to Password Protect (Basic), LDAP Authenticatione or use LemonLDAP:NG Handler
Includes Nginx Ultimate Bad Bot Blocker
Logrotate Included to roll over log files at 23:59, compress and retain for 7 days
Other features

Maintainer

Nfrastack

Installation

Prebuilt Images

Feature limited builds of the image are available on the Github Container Registry and Docker Hub.

To unlock advanced features, one must provide a code to be able to change specific environment variables from defaults. Support the development to gain access to a code.

To get access to the image use your container orchestrator to pull from the following locations:

ghcr.io/nfrastack/container-nginx:(image_tag)
docker.io/nfrastack/nginx:(image_tag)

The following image tags are available along with their tagged release based on what's written in the Changelog:

Alpine Base	Tag	Debian Base	Tag
latest	`:latest`	latest	`:debian`
latest	`:alpine`	Trixie	`:debian_trixie`
edge	`:alpine_edge`	Bookworm	`:debian_bookworm`
3.22	`:alpine_3.22`
3.19	`:alpine_3.19`
3.16	`:alpine_3.16`
3.15	`:alpine_3.15`
3.12	`:alpine_3.12`

Image tag syntax is:

<image>:<optional tag>-<optional_distribution>_<optional_distribution_variant>

Example:

ghcr.io/nfrastack/container-nginx:latest or

ghcr.io/nfrastack/container-nginx:1.0 or

ghcr.io/nfrastack/container-nginx:1.0-alpine or

ghcr.io/nfrastack/container-nginx:alpine or

ghcr.io/nfrastack/container-nginx:alpine_3.22

latest will be the most recent commit
An otpional tag may exist that matches the CHANGELOG - These are the safest
If it is built for multiple distributions there may exist a value of alpine or debian
If there are multiple distribution variations it may include a version - see the registry for availability

Have a look at the container registries and see what tags are available.

Multi-Architecture Support

Images are built for amd64 by default, with optional support for arm64 and other architectures.

Configuration

Quick Start

The quickest way to get started is using docker-compose. See the examples folder for a working compose.yml that can be modified for your use.
Map persistent storage for access to configuration and data files for backup.
Set various environment variables to understand the capabilities of this image.
Make networking ports available for public access if necessary

The container starts up and reads from /etc/nginx/nginx.conf for some basic configuration and to listen on port 73 internally for Nginx Status responses. Configuration of websites are done in /etc/nginx/sites.available with the filename pattern of site.conf. You must set an environment variable for NGINX_SITE_ENABLED if you have more than one configuration in there if you only want to enable one of the configurartions, otherwise it will enable all of them. Use NGINX_SITE_ENABLED=null to break a parent image declaration.

Use this as a starting point for your site configurations:

  server {
      ### Don't Touch This
      listen {{NGINX_LISTEN_PORT}};
      server_name localhost;
      root {{NGINX_WEBROOT}};
      ###

      ### Populate your custom directives here
      index  index.html index.htm;

      location / {
      #
      }

      ### Don't edit past here
}

Persistent Storage

The following directories are used for configuration and can be mapped for persistent storage.

Directory	Description
`/www/html`	Drop your web source files here to be served by Nginx
`/logs/nginx`	Logfiles for Nginx error and Access

Environment Variables

Base Images used

This image relies on a customized base image in order to work. Be sure to view the following repositories to understand all the customizable options:

Image	Description
OS Base	Base Image

Below is the complete list of available options that can be used to customize your installation.

Variables showing an 'x' under the Advanced column can only be set if the containers advanced functionality is enabled.

Core Configuration

Container Options

Parameter	Description	Default
`NGINX_MODE`	Set to `NORMAL`, `MAINTENANCE` , `PROXY`, `REDIRECT`	`NORMAL`
`NGINX_LISTEN_PORT`	Nginx listening port	`80`
`NGINX_USER`	What user to run nginx as inside container	`nginx`
`NGINX_GROUP`	What group to run nginx as inside container	`www-data`
`NGINX_WEBROOT`	Where to serve content from inside the container	`/www/html`

Logging Options

Parameter	Description	Default
`NGINX_LOG_ACCESS_FILE`	Nginx websites access logs	`access.log`
`NGINX_LOG_ACCESS_LOCATION`	Location inside container for saving logs	`/logs/nginx`
`NGINX_LOG_ACCESS_FORMAT`	Log Format `standard` or `json`	`standard`
`NGINX_LOG_BLOCKED_FILE`	If exploit protection `TRUE`	`access.log`
`NGINX_LOG_BLOCKED_LOCATION`	Location inside container for saving logs	`/logs/nginx`
`NGINX_LOG_BLOCKED_FORMAT`	Log Format `standard` or `json`	`standard`
`NGINX_LOG_ERROR_FILE`	Nginx server and websites error log name	`error.log`
`NGINX_LOG_ERROR_LOCATION`	Location inside container for saving logs	`/logs/nginx`
`NGINX_LOG_LEVEL_ERROR`	How much verbosity to use with error logs	`warn`

Functionality Options

Parameter	Description	Default
`NGINX_FORCE_RESET_PERMISSIONS`	Force setting Nginx files ownership to web server user	`TRUE`
`NGINX_REDIRECT_URL`	If `REDIRECT` set enter full url to forward all traffic to eg `https://example.com`
`NGINX_RESOLVER`	Resolve hostnames via DNS. Space seperated values. e.g. `127.0.0.11`
`NGINX_PROXY_URL`	If `REDIRECT` set enter full url to proxy all traffic to eg `https://example.com:443`
`NGINX_SITE_ENABLED`	What sites to enable in `/etc/nginx/sites.available` Don't use `.conf` suffix	`ALL`
`NGINX_ENABLE_APPLICATION_CONFIGURATION`	Don't automatically setup /etc/nginx/sites.available files
	Useful for volume mapping/overriding	`TRUE`
`NGINX_ENABLE_CREATE_SAMPLE_HTML`	If no index.html found - create a sample one to prove container works	`TRUE`
`NGINX_ENABLE_SITE_OPTIMIZATIONS`	Deny access to some files and URLs, send caching tags	`TRUE`
`NGINX_ENABLE_METRICS`	Enable monitoring endpoint on port 127.0.0.1:73	`TRUE`
`NGINX_INCLUDE_CONFIGURATION`	Include configuration in your website application file. eg `/www/website/nginx.conf`
`NGINX_RELOAD_ON_CONFIG_CHANGE`	Automatically reload nginx on configuration file change	`FALSE`
`NGINX_POST_INIT_SCRIPT`	If you wish to run a bash script before the nginx process runs
	enter the path here, seperate multiple by commas.
`NGINX_WEBROOT_SUFFIX`	Append a suffix onto the nginx configuration to serve files
	from a subfolder e.g. `/public`

If NGINX_MODE set to MAINTNENANCE a single page will show visitors that the server is being worked on.

Maintenance Options

Parameter	Description	Default
`NGINX_MAINTENANCE_TYPE`	Serve `local` file or `redirect` or `proxy` to a URL	`local`
`NGINX_MAINTENANCE_PATH`	(local) Path where the maintenance page resides	`/container/data/nginx/maintenance`
`NGINX_MAINTENANCE_FILE`	(local) File to load while in maintenance mode	`index.html`
`NGINX_MAINTENANCE_REMOTE_URL`	(local) If you wish to download an html file from a
	remote location to overwrite the above enter the URL here
`NGINX_MAINTENANCE_PROXY_URL`	What url eg `https://example.com` to transparently proxy for
	the user when they visit the site	`http://maintenance`
`NGINX_MAINTENANCE_REDIRECT_URL`	What url eg `https://example.com` to redirect
	in a uers browser when they visit the site

You can also enter into the container and type maintenance ARG, where ARG is either ON,OFF, or SLEEP (seconds) which will temporarily place the site in maintenance mode and then restore it back to normal after time has passed.

Reverse Proxy Options

Parameter	Description	Default
`NGINX_ENABLE_FASTCGI_HTTPS`	Set fastcgi_param HTTPS 'on'	`FALSE`
`NGINX_ENABLE_REVERSE_PROXY`	Helpers for when behind a reverse proxy	`TRUE`
`NGINX_REAL_IP_HEADER`	What is the header passed containing the visitors IP	`X-Forwarded-For`
`NGINX_SET_REAL_IP_FROM`	Set the network of your Docker Network if having IP lookup issues	`172.16.0.0/12`

Authentication Options

You can choose to request visitors be authenticated before accessing your site. Options are below.

Parameter	Description	Default	`_FILE`	Advanced
`NGINX_AUTHENTICATION_TYPE`	Protect the site with `BASIC`, `LDAP`, `LLNG`	`NONE`
`NGINX_AUTHENTICATION_TITLE`	Challenge response when visiting protected site	`Please login`
`NGINX_AUTHENTICATION_BASIC_USER1`	If `BASIC` chosen enter this for the username to protect site	`admin`	x
`NGINX_AUTHENTICATION_BASIC_PASS1`	If `BASIC` chosen enter this for the password to protect site	`nfrastack`	x
`NGINX_AUTHENTICATION_BASIC_USER2`	As above, increment for more users		x
`NGINX_AUTHENTICATION_BASIC_PASS2`	As above, increment for more users		x
`NGINX_AUTHENTICATION_LDAP_HOST`	Hostname and port number of LDAP Server - eg `ldap://ldapserver:389`		x
`NGINX_AUTHENTICATION_LDAP_BIND_DN`	User to Bind to LDAP - eg `cn=admin,dc=orgname,dc=org`		x
`NGINX_AUTHENTICATION_LDAP_BIND_PW`	Password for Above Bind User - eg `password`		x
`NGINX_AUTHENTICATION_LDAP_BASE_DN`	Base Distringuished Name - eg `dc=hostname,dc=com`		x
`NGINX_AUTHENTICATION_LDAP_ATTRIBUTE`	Unique Identifier Attrbiute -ie `uid`			x
`NGINX_AUTHENTICATION_LDAP_SCOPE`	LDAP Scope for searching - eg `sub`			x
`NGINX_AUTHENTICATION_LDAP_FILTER`	Define what object that is searched for (ie `objectClass=person`)			x
`NGINX_AUTHENTICATION_LDAP_GROUP_ATTRIBUTE`	If searching inside of a group what is the Group Attribute - eg `uniquemember`			x
`NGINX_AUTHENTICATION_LLNG_HANDLER_HOST`	If `LLNG` chosen use hostname and port of handler.
	Add multiple by seperating with comments	`llng-handler:2884`	x
`NGINX_AUTHENTICATION_LLNG_HANDLER_PORT`	If `LLNG` chosen use this port for handler	`2884`	x
`NGINX_AUTHENTICATION_LLNG_BUFFERS`	FastCGI Buffers for performance	`32 32k`		x
`NGINX_AUTHENTICATION_LLNG_BUFFER_SIZE`	FastCGI Buffer size for performance	`32k`		x
`NGINX_AUTHENTICATION_LLNG_ATTRIBUTE1`	Syntax: HEADER_NAME, Variable, Upstream Variable - See note below
`NGINX_AUTHENTICATION_LLNG_ATTRIBUTE2`	Syntax: HEADER_NAME, Variable, Upstream Variable - See note below

When working with NGINX_AUTHENTICATION_LLNG_ATTRIBUTE2 you will need to omit any $ chracters from your string. It will be added in upon container startup.

Example: NGINX_AUTHENTICATION_LLNG_ATTRIBUTE1=HTTP_AUTH_USER,uid,upstream_http_uid will get converted into HTTP_AUTH_USER,$uid,$upstream_http_uid and get placed in the appropriate areas in the configuration.

Bot Blocking Options

Parameter	Description	Default	Advanced
`NGINX_ENABLE_BLOCK_BOTS`	Block Bots and Crawlers	`FALSE`
`NGINX_BLOCK_BOTS_WHITELIST_DOMAIN`	Domains to whitelist from blocking comma seperated
	e.g. `example1.com,example2.com`
`NGINX_BLOCK_BOTS_WHITELIST_IP`	IP Addresses/Networks to Whitelist from Blocking comma seperated	`127.0.0.1,10.0.0.0/8,`	x
		`172.16.0.0/12,192.168.0.0/24`
`NGINX_BLOCK_BOTS`	Bots to Block
	`ALL` `AOL` `BING` `DOCOMO` `DUCKDUCKGO`
	`FACEBOOK` `GOOGLE` `LINKEDIN` `MISC` `MSN`
	`SAMSUNG` `SLACK` `SLURP` `TWITTER` `WORDPRESS`
	`YAHOO` or `yourcustom-useragent` in Comma Seperated values

For more details on how Bot Blocking works please visit Nginx Ultimate Bad Bot Blocker

Compression Options

Presently you can compress your served content with gzip and brotli. More compression options to come in future..

Parameter	Description	Default	Advanced
`NGINX_ENABLE_COMPRESSION_BROTLI`	Enable Brotli Compression	`TRUE`
`NGINX_COMPRESSION_BROTLI_LEVEL`	Compression Level for Brotli	`6`	x
`NGINX_COMPRESSION_BROTLI_MIN_LENGTH`	Minimum length of content before compressing	`20`	x
`NGINX_COMPRESSION_BROTLI_TYPES`	What filetypes to compress	`text/plain text/css text/xml`	x
		`text/javascript application/x-javascript`
		`application/json application/xml`
`NGINX_COMPRESSION_BROTLI_WINDOW`		`512k`	x
`NGINX_ENABLE_COMPRESSION_GZIP`	Enable GZIP Compression	`TRUE`
`NGINX_COMPRESSION_GZIP_BUFFERS`		`16 8k`	x
`NGINX_COMPRESSION_GZIP_DISABLE`	Don't compress for these user agents	`MSIE [1-6].(?!.*SV1)`	x
`NGINX_COMPRESSION_GZIP_HTTP_VERSION`		`1.1`	x
`NGINX_COMPRESSION_GZIP_LEVEL`	Compression Level	`6`	x
`NGINX_COMPRESSION_GZIP_MIN_LENGTH`	Minimum length of content before compressing	`10240`	x
`NGINX_COMPRESSION_GZIP_PROXIED`		`expired no-cache no-store private auth`	x
`NGINX_COMPRESSION_GZIP_TYPES`	Types of content to compress	`text/plain text/css`	x
		`text/xml text/javascript`
		`application/x-javascript application/json`
		`application/xml`
`NGINX_COMPRESSION_GZIP_VARY`		`TRUE`	x

DDoS Options

Parameter	Description	Default	Advanced
`NGINX_ENABLE_DDOS_PROTECTION`	Enable simple DDoS Protection	`FALSE`
`NGINX_DDOS_CONNECTIONS_PER_IP`	Limit amount of connections per IP	`10m`	x
`NGINX_DDOS_REQUESTS_PER_IP`	Limit amount of requests per IP	`5r/s`	x

Performance Options

Parameter	Description	Default	Advanced
`NGINX_CACHE_OPEN_FILE_ERRORS`	Cache errors like 404	`TRUE`	x
`NGINX_CACHE_OPEN_FILE_INACTIVE`	Stop caching after inactive	`5m`	x
`NGINX_CACHE_OPEN_FILE_MAX`	Maximum files to cache	`200000`	x
`NGINX_CACHE_OPEN_FILE_MIN_USES`	Minimum uses of file before cashing	`2`	x
`NGINX_CACHE_OPEN_FILE_VALID`	Cache a file if has been accessed within this window	`2m`	x
`NGINX_CLIENT_BODY_BUFFER_SIZE`	Client Buffer size	`16k`	x
`NGINX_CLIENT_BODY_TIMEOUT`	Request time out	`60`	x
`NGINX_ENABLE_EPOLL`	Optmized to serve many clients with each thread, essential for linux	`TRUE`
`NGINX_ENABLE_MULTI_ACCEPT`	Accept as many connections as possible, may flood worker connections if set too low	`TRUE`
`NGINX_ENABLE_OPEN_FILE_CACHE`	Cache informations about FDs, frequently accessed files	`TRUE`
`NGINX_ENABLE_PROXY_BUFFERING`	Enable Proxy Buffering	`TRUE`
`NGINX_ENABLE_RESET_TIMEDOUT_CONNECTION`	Allow the server to close connection on non responding client, this will free up memory	`TRUE`
`NGINX_ENABLE_SENDFILE`	Copies data between one FD and other from within the kernel	`TRUE`
`NGINX_ENABLE_SERVER_TOKENS`	Show Nginx version on responses	`FALSE`
`NGINX_ENABLE_TCPNODELAY`	Don't buffer data sent, good for small data bursts in real time	`TRUE`
`NGINX_ENABLE_TCPNOPUSH`	Send headers in one peace, its better then sending them one by one	`TRUE`
`NGINX_ENABLE_UPSTREAM_KEEPALIVE`	Reuse connections when using upstream (LLNG Auth, FastCGI etc)	`TRUE`
`NGINX_FASTCGI_BUFFER_SIZE`	FastCGI Buffer Size	`32k`	x
`NGINX_FASTCGI_BUFFERS`	Amount of FastCGI Buffers	`16 16k`	x
`NGINX_KEEPALIVE_REQUESTS`	Number of requests client can make over keep-alive	`100000`	x
`NGINX_KEEPALIVE_TIMEOUT`	Server will close connection after this time	`75`	x
`NGINX_PROXY_BUFFER_SIZE`	Proxy Buffer Size	`128k`	x
`NGINX_PROXY_BUFFERS`	Proxy Buffers	`4 256k`	x
`NGINX_PROXY_BUSY_BUFFERS_SIZE`	Proxy Busy Buffers Size	`256k`	x
`NGINX_SEND_TIMEOUT`	If client stop responding, free up memory	`60`	x
`NGINX_SERVER_NAMES_HASH_BUCKET_SIZE`	Server names hash size (256`` if NGINX_ENABLE_BLOCK_BOTS=TRUE`)	`32`	x
`NGINX_UPLOAD_MAX_SIZE`	Maximum Upload Size	`2G`
`NGINX_UPSTREAM_KEEPALIVE`	Keepalive connections to utilize for upstream	`32`	x
`NGINX_WORKER_CONNECTIONS`	Determines how much clients will be served per worker	`1024`	x
`NGINX_WORKER_PROCESSES`	How many processes to spawn	`1`
`NGINX_WORKER_RLIMIT_NOFILE`	Number of file descriptors used for nginx	`100000`	x

Client Cache Configuration

Parameter	Description	Default	Advanced
`NGINX_ENABLE_CLIENT_CACHE`	`ALL` `site-name` `FALSE` Enabling Client caching	`ALL`
`NGINX_CLIENT_CACHE`	Types of client cache to enable (AUDIO,CSS,HTML,IMAGE,JS,MISC,VIDEO)	`AUDIO,CSS,HTML,IMAGE,JS,MISC,VIDEO`	x
`NGINX_CLIENT_CACHE_AUDIO_EXPIRES`	Audio cache expiration	`15d`	x
`NGINX_CLIENT_CACHE_AUDIO_EXTENSIONS`	Audio file extensions to cache	`mp3 ogg wav`	x
`NGINX_CLIENT_CACHE_AUDIO_LOG`	Enable logging for audio cache	`TRUE`	x
`NGINX_CLIENT_CACHE_CSS_EXPIRES`	CSS cache expiration	`30d`	x

Users and Groups

Type	Name	ID
User	`nginx`	80
Group	`www-data`	82

Networking

Port	Protocol	Description
`80`	tcp	Nginx

Maintenance

Shell Access

For debugging and maintenance, bash and sh are available in the container.

Support & Maintenance

For community help, tips, and community discussions, visit the Discussions board.
For personalized support or a support agreement, see Nfrastack Support.
To report bugs, submit a Bug Report. Usage questions will be closed as not-a-bug.
Feature requests are welcome, but not guaranteed. For prioritized development, consider a support agreement.
Updates are best-effort, with priority given to active production use and support agreements.

References

https://nginx.org/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 284 Commits
.github		.github
examples		examples
rootfs		rootfs
zabbix_templates		zabbix_templates
.dockerignore		.dockerignore
CHANGELOG.md		CHANGELOG.md
Containerfile		Containerfile
LICENSE		LICENSE
README.md		README.md

Uh oh!

License

nfrastack/container-nginx

Folders and files

Latest commit

History

Repository files navigation

nfrastack/container-nginx

About

Maintainer

Table of Contents

Installation

Prebuilt Images

Multi-Architecture Support

Configuration

Quick Start

Persistent Storage

Environment Variables

Base Images used

Core Configuration

Container Options

Logging Options

Functionality Options

Maintenance Options

Reverse Proxy Options

Authentication Options

Bot Blocking Options

Compression Options

DDoS Options

Performance Options

Client Cache Configuration

Users and Groups

Networking

Maintenance

Shell Access

Support & Maintenance

References

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 82

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages