Awesome

Nginx Docker Container Images

• Docker images
• Environment variables
• Build arguments
• Nginx modules
  • ModSecurity
• 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

❗For better reliability we release images with stability tags (wodby/nginx:1.26-X.X.X) which correspond to git tags. We strongly recommend using images only with stability tags.

Overview:

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

Supported tags and respective Dockerfile links:

• 1.27, 1, latest (Dockerfile)
• 1.26 (Dockerfile)

All images built for linux/amd64 and linux/arm64

Environment Variables

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

Nginx modules

ModSecurity

Compiled as a dynamic module, disabled by default. To enable set $NGINX_MODSECURITY_ENABLED to any value. Additionally, you can enable OWASP Core Rule Set (CRS) by setting $NGINX_MODSECURITY_USE_OWASP_CRS to any value, ️be wary since it may block some requests with the default configuration. See env vars starting with $NGINX_MODSECURITY_ for advanced configuration.

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
• /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:

HTTP proxy (application server)

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

Overridden default values:

Django

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

• Preset template
• Usage: add NGINX_VHOST_PRESET=django

Overridden default values:

PHP-based (FastCGI)

Overridden default values:

PHP

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

Overridden default values:

Laravel

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

Overridden default values:

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'

Default value of NGINX_WP_NOT_FOUND_REGEX (backspaces must be escaped) is: .+\\.(?:txt|md|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
• 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 certs 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'

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|md|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