Nginx Docker Container Images

• Docker images
• Environment variables
• Build arguments
• Nginx modules
• Default behaviour
• Customization
• Virtual hosts presets
  • HTML
  • HTTP proxy (application server)
  • Django
  • PHP-based (FastCGI)
    • PHP
    • Laravel
    • WordPress
    • Drupal
    • Matomo
  • Custom preset
  • No preset
• Orchestration actions

Docker Images

Use image revision tags such as wodby/nginx:1.31-rN to select a Wodby image revision. Major and minor tags use the repository release number, starting at r0. Full-version tags such as wodby/nginx:1.31.6-r0 start at r0 for each exact upstream version. Every published versioned revision tag has a matching annotated Git tag pointing to its release commit. Existing tags remain available after support for their major or minor version ends. See release tags for available revisions and the image revision policy for upgrade guidance. Previously published image tags remain available.

Overview:

• All images are based on Alpine Linux
• Base image: wodby/alpine
• GitHub actions builds
• Docker Hub

Supported tags and respective Dockerfile links:

• 1.31, 1, latest (Dockerfile)
• 1.30 (Dockerfile)

All images built for linux/amd64 and linux/arm64

Environment Variables

Variable	Default Value	Description
NGINX_ALLOW_ACCESS_HIDDEN_FILES
NGINX_BACKEND_FAIL_TIMEOUT	0
NGINX_BACKEND_HOST	Varies with a preset
NGINX_BACKEND_PORT	Varies with a preset
NGINX_BROTLI	on
NGINX_BROTLI_STATIC	on
NGINX_BROTLI_COMP_LEVEL	1
NGINX_CLIENT_BODY_BUFFER_SIZE	16k
NGINX_CLIENT_BODY_TIMEOUT	60s
NGINX_CLIENT_HEADER_BUFFER_SIZE	4k
NGINX_CLIENT_HEADER_TIMEOUT	60s
NGINX_CLIENT_MAX_BODY_SIZE	32m
NGINX_CONF_INCLUDE	conf.d/*.conf
NGINX_DISABLE_CACHING
NGINX_DJANGO_MEDIA_ROOT	/var/www/html/media/
NGINX_DJANGO_MEDIA_URL	/media/
NGINX_DJANGO_STATIC_ROOT	/var/www/html/static/
NGINX_DJANGO_STATIC_URL	/static/
NGINX_DRUPAL_ALLOW_XML_ENDPOINTS
NGINX_DRUPAL_FILE_PROXY_URL		e.g. http://dev.example.com
NGINX_DRUPAL_FILES_STATIC_EXT_REGEX	txt
NGINX_DRUPAL_HIDE_HEADERS
NGINX_DRUPAL_XMLRPC_SERVER_NAME		Drupal 7 only
NGINX_DRUPAL_NOT_FOUND_REGEX	(see Drupal)
NGINX_DRUPAL_REMOVE_INDEXPHP	(see Drupal)
NGINX_WP_NOT_FOUND_REGEX	(see Wordpress)
NGINX_ERROR_403_URI
NGINX_ERROR_404_URI
NGINX_ERROR_LOG_LEVEL	error
NGINX_ERROR_MESSAGE_50x
NGINX_FASTCGI_BUFFER_SIZE	32k	For PHP-based presets only
NGINX_FASTCGI_BUFFERS	16 32k	For PHP-based presets only
NGINX_FASTCGI_INDEX	index.php	For PHP-based presets only
NGINX_FASTCGI_INTERCEPT_ERRORS	on	For PHP-based presets only
NGINX_FASTCGI_READ_TIMEOUT	900	For PHP-based presets only
NGINX_GZIP_BUFFERS	16 8k
NGINX_GZIP_COMP_LEVEL	1
NGINX_GZIP_DISABLE	msie6
NGINX_GZIP_HTTP_VERSION	1.1
NGINX_GZIP_MIN_LENGTH	20
NGINX_GZIP_PROXIED	any
NGINX_GZIP_VARY	on
NGINX_GZIP	on
NGINX_HEADERS_CONTENT_SECURITY_POLICY	frame-ancestors 'none'	different for Drupal and WP presets
NGINX_HIDE_50x_ERRORS
NGINX_HTTP2
NGINX_INDEX_FILE	Varies with a preset	Hard-coded for Drupal and WP
NGINX_KEEPALIVE_REQUESTS	100
NGINX_KEEPALIVE_TIMEOUT	75s
NGINX_LARGE_CLIENT_HEADER_BUFFERS	8 16k
NGINX_LOG_FORMAT_OVERRIDE
NGINX_METRICS_ENABLED	off
NGINX_METRICS_FORMAT	html	html, json, jsonp, prometheus
NGINX_METRICS_ALLOW_FROM
NGINX_MULTI_ACCEPT	on
NGINX_NO_DEFAULT_HEADERS
NGINX_REAL_IP_HEADER	X-Real-IP
NGINX_REAL_IP_RECURSIVE	off
NGINX_RESET_TIMEDOUT_CONNECTION	off
NGINX_SEND_TIMEOUT	60s
NGINX_SENDFILE	on
NGINX_SERVER_EXTRA_CONF_FILEPATH
NGINX_SERVER_NAME	default
NGINX_SERVER_ROOT	/var/www/html
NGINX_SERVER_TOKENS	off
NGINX_SERVER_PORT	80
NGINX_SET_REAL_IP_FROM
NGINX_SET_REAL_IPS_FROM		json array as string
NGINX_STATIC_404_TRY_INDEX
NGINX_STATIC_ACCESS_LOG	off
NGINX_STATIC_EXPIRES	1y
NGINX_STATIC_MP4_BUFFER_SIZE	1M
NGINX_STATIC_MP4_MAX_BUFFER_SIZE	5M
NGINX_STATIC_OPEN_FILE_CACHE_ERRORS	on
NGINX_STATIC_OPEN_FILE_CACHE_MIN_USES	2
NGINX_STATIC_OPEN_FILE_CACHE_VALID	30s
NGINX_STATIC_OPEN_FILE_CACHE	max=1000 inactive=30s
NGINX_STATIC_EXT_REGEX	(see below)
NGINX_STATUS_ALLOW_FROM		e.g. 172.18.0.0/16
NGINX_STATUS_ENABLED	off
NGINX_TCP_NODELAY	on
NGINX_TCP_NOPUSH	on
NGINX_TRACK_UPLOADS	uploads 60s
NGINX_UNDERSCORES_IN_HEADERS	off
NGINX_UPLOAD_PROGRESS	uploads 1m
NGINX_USER	nginx	wodby when WODBY_WORKSPACE=1
NGINX_VHOST_NO_DEFAULTS
NGINX_VHOST_PRESET	html
NGINX_WORKER_CONNECTIONS	1024
NGINX_WORKER_PROCESSES	auto
NGINX_WP_FILE_PROXY_URL		e.g. http://dev.example.com
NGINX_WP_GOOGLE_XML_SITEMAP		See WordPress
NGINX_WP_YOAST_XML_SITEMAP		See WordPress

Static files extension defined via the regex and can be overridden via the env var NGINX_STATIC_EXT_REGEX, default:

css|cur|js|jpe?g|gif|htc|ico|png|xml|otf|ttf|eot|woff|woff2|svg|mp4|svgz|ogg|ogv|pdf|pptx?|zip|tgz|gz|rar|bz2|doc|xls|exe|tar|mid|midi|wav|bmp|rtf|txt|map|webp

Some environment variables can be overridden or added per preset.

Build arguments

Argument	Default value
WODBY_GROUP_ID	1000
WODBY_USER_ID	1000

Nginx modules

Name	Version	Dynamic
brotli	a71f9312
http_addition
http_auth_request
http_dav
http_flv
http_gunzip
http_gzip_static
http_image_filter		✓
http_mp4
http_random_index
http_realip
http_secure_link
http_slice
http_ssl
http_stub_status
http_sub
http_uploadprogress	0.9.4
http_v2
mail_ssl
stream_realip
stream_ssl
stream_ssl_preread
vts	0.2.4

Default behavior

Applied to all presets by default, can be disabled via $NGINX_VHOST_NO_DEFAULTS:

• /.well-known/ location supported
• /ads.txt allowed
• /robots.txt allowed
• /llms.txt allowed
• /humans.txt allowed
• /favicon.ico allowed
• .flv, .m4a, .mp4, .mov locations supported and handled with appropriate modules
• /.healthz location supported, requests not shown in access log

Customization

• Pass real IP from a reverse proxy via $NGINX_SET_REAL_IP_FROM, e.g. 172.17.0.0/16 for docker network
• Pass multiple real IP from reverse proxies via $NGINX_SET_REAL_IPS_FROM In a compose.yml this can be done like this:

  environment:
    NGINX_SET_REAL_IPS_FROM: "[\"172.17.0.0/16\", \"192.168.0.10\"]"
  
  environment:
    NGINX_SET_REAL_IPS_FROM: |-
      ["172.17.0.0/16", "192.168.0.10"]
  

• Customize the header which value will be used to replace the client address via $NGINX_REAL_IP_HEADER
• Default recommended headers can be disabled via $NGINX_NO_DEFAULT_HEADERS (defined in nginx.conf)
• The value for the Content-Security-Policy header can be changed using $NGINX_HEADERS_CONTENT_SECURITY_POLICY, it's default value is frame-ancestors 'none'. More information on this header can be found here.
• Error page file can be customized for HTTP errors 403 ($NGINX_ERROR_403_URI) and 404 ($NGINX_ERROR_404_URI)
• Default error page for HTTP errors 500, 502, 503, 504 can be disabled via $NGINX_HIDE_50x_ERRORS
• Access to hidden files (starting with .) can be allowed via $NGINX_ALLOW_ACCESS_HIDDEN_FILES
• Caching can be disabled via $NGINX_DISABLE_CACHING
• Add extra locations via $NGINX_SERVER_EXTRA_CONF_FILEPATH=/filepath/to/nginx-locations.conf, the file will be included at the end of default rules (server context)
• Completely override include of the virtual host config by overriding NGINX_CONF_INCLUDE, it will be included in nginx.conf
• Define custom preset
• Status page /.statusz can be enabled via $NGINX_STATUS_ENABLED, requests not shown in access log
• Metrics page /.metricsz can be enabled via $NGINX_METRICS_ENABLED, requests not shown in access log
• Metrics page format can be customized via $NGINX_METRICS_FORMAT, supports json, html, jsonp and prometheus

Virtual hosts presets

Virtual host preset html will be used by default, you can change it via env var $NGINX_VHOST_PRESET. The list of available presets:

HTML

• Preset template
• Usage: this preset selected by default

Overridden default values:

Variable	Default Value
NGINX_INDEX_FILE	index.html

HTTP proxy (application server)

• Preset template
• Usage: add NGINX_VHOST_PRESET=http-proxy and NGINX_BACKEND_HOST=[HOST]

Overridden default values:

Variable	Default Value
NGINX_BACKEND_HOST
NGINX_BACKEND_PORT	8080

Django

Same as HTTP proxy but with additional media/static locations for Django.

• Preset template
• Usage: add NGINX_VHOST_PRESET=django

Overridden default values:

Variable	Default Value
NGINX_BACKEND_HOST	python
NGINX_BACKEND_PORT	8080

PHP-based (FastCGI)

Overridden default values:

Variable	Default Value
NGINX_BACKEND_HOST	php
NGINX_BACKEND_PORT	9000

PHP

• Preset template
• Usage: add NGINX_VHOST_PRESET=php, optionally modify NGINX_BACKEND_HOST

Overridden default values:

Variable	Default Value
NGINX_INDEX_FILE	index.php index.html

Laravel

• Preset template
• Usage: add NGINX_VHOST_PRESET=laravel, optionally modify NGINX_BACKEND_HOST

Overridden default values:

Variable	Default Value
NGINX_INDEX_FILE	index.php index.html

WordPress

• Preset template
• Usage: add NGINX_VHOST_PRESET=wordpress, optionally modify NGINX_BACKEND_HOST
• Access to *.txt files allowed only if they are located in uploads directory
• Access to /wp-content/uploads/woocommerce_uploads disallowed
• Dynamic generated /robots.txt supported
• Supports /wp-sitemap.xml endpoint
• Alternative sitemap.xml endpoints:
  • For plugin Google XML Sitemap add $NGINX_WP_GOOGLE_XML_SITEMAP=1
  • For plugin Yoast SEO add $NGINX_WP_YOAST_XML_SITEMAP=1
• Default value of NGINX_HEADERS_CONTENT_SECURITY_POLICY overridden to frame-ancestors 'self'
• Files INSTALL.md, README.md, LICENSE.md, FAQ.md and CHANGELOG.md inside plugins directory return 404

Default value of NGINX_WP_NOT_FOUND_REGEX (backspaces must be escaped) is: .+\\.(?:txt|pot|sh|.*sql?)|(?:composer\\.(json|lock)|(package|package-lock)\\.json|yarn\\.lock)$

Drupal

• Preset templates: Drupal 11, Drupal 10, Drupal 9, Drupal 8, Drupal 7
• Usage: add NGINX_VHOST_PRESET= with the value of drupal11, drupal10, drupal9, drupal8 or drupal7. Optionally modify NGINX_BACKEND_HOST
• If you want to use stage_file_proxy module, set $NGINX_STATIC_404_TRY_INDEX=1 to redirect 404 static files requests to Drupal
• With NGINX_DRUPAL_FILE_PROXY_URL set, missing files in the files directory redirect to that URL. A missing image style goes to Drupal first, so it is built when the source image exists locally; it redirects to the URL only when Drupal answers 404 (or 403 on Drupal 7)
• Access to .txt (can be overridden via NGINX_DRUPAL_FILES_STATIC_EXT_REGEX) files allowed only if they are located in files directory
• Access to cert extensions gives 404 based on the value of $NGINX_DRUPAL_NOT_FOUND_REGEX
• Default value of NGINX_HEADERS_CONTENT_SECURITY_POLICY overridden to frame-ancestors 'self'
• Set NGINX_DRUPAL_REMOVE_INDEXPHP to any value to remove index.php from the URL, e.g. index.php/node/abc will redirect to /node/abc
• Files INSTALL.md, README.md, LICENSE.md, FAQ.md and CHANGELOG.md inside modules directory return 404

Default value of NGINX_DRUPAL_NOT_FOUND_REGEX (backspaces must be escaped) is taken from Drupal's .htaccess and depends on the Drupal version:

Drupal 11/10/9/8:

\\.(engine|txt|inc|install|make|module|profile|po|sh|.*sql|theme|twig|tpl(\\.php)?|xtmpl|yml|yaml)(~|\\.sw[op]|\\.bak|\\.orig|\\.save)?$|^(\\.(?!well-known).*|Entries.*|Repository|Root|Tag|Template)$|(web\\.config|composer\\.(json|lock)|(package|package-lock)\\.json|yarn\\.lock)$|^#.*#$|\\.php(~|\\.sw[op]|\\.bak|\\.orig|\\.save)$

Drupal 7:

\\.(engine|txt|inc|info|install|make|module|profile|test|po|sh|.*sql|theme|tpl(\\.php)?|xtmpl|yml|yaml)(~|\\.sw[op]|\\.bak|\\.orig|\\.save)?$|^(\\.(?!well-known).*|Entries.*|Repository|Root|Tag|Template|composer\\.(json|lock)|(package|package-lock)\\.json|yarn\\.lock)$|^#.*#$|\\.php(~|\\.sw[op]|\\.bak|\\.orig\\.save)$

Matomo

Based on https://github.com/matomo-org/matomo-nginx

The default value of NGINX_STATIC_EXT_REGEX overridden:

css|cur|js|jpe?g|gif|htc|ico|png|xml|otf|ttf|eot|woff|woff2|svg|mp4|svgz|ogg|ogv|pdf|pptx?|zip|tgz|gz|rar|bz2|doc|xls|exe|tar|mid|midi|wav|bmp|rtf|txt|map|webp|json|html

Custom preset

You can use a custom by preset by mounting your preset to /etc/gotpl/presets/[my-preset-name].conf.tmpl and setting $NGINX_VHOST_PRESET=[my-preset-name].

No preset

To disable presets set $NGINX_VHOST_PRESET=""

Maintenance

Updates to Nginx and base image automated via wodby/images.

Orchestration actions

Usage:

make COMMAND [params ...]

commands:
    init
    git-checkout [target is_hash]
    check-ready [host max_try wait_seconds delay_seconds]

default params values:
    host localhost
    max_try 1
    wait_seconds 1
    delay_seconds 0

Building with pinned base images

Build with the Makefile to use the base image digests in base-images.mk. Local builds and CI resolve the same version and variant to the same multi-platform image. A version without a pin fails before the build starts.

When adding a supported base version or variant, add its image index digest to base-images.mk. For a custom build, override BASE_IMAGE with a complete repository:tag@sha256:... reference.