tundrasoft/nginx repository overview

⁠TundraSoft - Nginx

Docker image for Nginx web server. It contains few custom modules pre-installed which pack a bit more of a punch to the nginx server

⁠Usage

@TODO

⁠Using Image

@TODO

⁠Building image

docker build . --cpuset-cpus 0-3  --no-cache --build-arg NGINX_VERSION=1.25.1 --build-arg ALPINE_VERSION=latest --platform=linux/x86_64 -t tundrasoft/nginx

⁠Volumes

Below volumes are exported by default:

• /acme - Contains certificates generated by acme
• /crons - Folder where cron jobs can be added. By default 2 files are present
  • maxmind_refresh - Refreshes maxmind database
  • nginx_reload - cron to reload nginx if config has changed
• /etc/nginx - The main nginx config path. contains all configuration options
  • certs - All certificate files are stored here
  • defaults - Default configuration partials are stored here
    • modsecurity - Modsecurity configuration stored here
  • modules - Dynamic module files are present here NOTE Modules will be copied dynamically on boot
  • sites.d - All site configurations are present here
    • 0-default.conf - (Generated) - Default config blocking undefined access
  • modules.conf - List of enabled modules
  • nginx.conf - Main config file
• /var/log/nginx - All logs are stored here
• /webroot - This is the webroot where any static content can be placed. By default this will contain the below directories:
  • defaults
    • fancy-index - page index templates
    • 50x.html - Default 50x error page
    • 404.html - Default 404 error page
    • index.htmk - Default index template
  • ${TLD} - Any other domain's webroot

The folder /etc/nginx/conf.d/ contains partial configuration files for different modules which can be included in your site configuration to activate them. They are meant to be generic and not for special use cases (basically a good starting point).

⁠Configuration

⁠Adding a new site

One step process using nginx-ctl:

nginx-ctl add-site -d SITE_NAME -d ALT_SITE_NAME --with-modsecurity --enable-stub-status --enable-ping

OR

Create a custom nginx server configuration in path - /etc/nginx/sites.d Try to follow the template file /templates/site.conf.template and also ensure the file name is following the naming convention of SITE_NAME.conf, example for google.com it would be google.com.conf.

Once done, you can either wait for nginx auto reload to reload new configuration or force reload yourself by running in container:

nginx-ctl reload

⁠Disabling site

Simple onestep process using nginx-ctl:

nginx-ctl disable-site SITE_NAME

OR

Go to path /etc/nginx/sites.d and rename the site's config file from SITE_NAME.conf to SITE_NAME.conf.disabled Once done, either wait for autoreload to reload nginx config or run in container:

nginx-ctl reload

⁠Enabling a disabled site

Simple onestep process using nginx-ctl:

nginx-ctl enable-site SITE_NAME

OR

Go to path /etc/nginx/sites.d and rename the site's config file from SITE_NAME.conf.disabled to SITE_NAME.conf. Once done, either wait for autoreload to reload nginx config or run in container:

nginx-ctl reload

⁠Generating SSL (lets encrypt etc)

@TODO

⁠Modules & Components

⁠Core Modules

--with-http_ssl_module
--with-http_gzip_static_module
--with-http_v2_module
--with-http_stub_status_module
--with-http_realip_module https://nginx.org/en/docs/http/ngx_http_realip_module.html
--with-http_addition_module https://nginx.org/en/docs/http/ngx_http_addition_module.html
--with-http_xslt_module https://nginx.org/en/docs/http/ngx_http_xslt_module.html 
--with-stream https://nginx.org/en/docs/stream/ngx_stream_core_module.html
--without-http_ssi_module

⁠Third Party

⁠Nginx upstream jDomain⁠

This module allows you to use a domain name in an upstream block and expect the domain name to be dynamically resolved so your upstream may be resilient to DNS entry updates.

⁠Fancy Index⁠

The Fancy Index module makes possible the generation of file listings, like the built-in autoindex module does, but adding a touch of style. This is possible because the module allows a certain degree of customization of the generated content:

• Custom headers, either local or stored remotely.
• Custom footers, either local or stored remotely.
• Add your own CSS style rules.
• Allow choosing to sort elements by name (default), modification time, or size; both ascending (default), or descending.

⁠GeoIP2⁠

creates variables with values from the maxmind geoip2 databases based on the client IP (default) or from a specific variable (supports both IPv4 and IPv6)

The module now supports nginx streams and can be used in the same way the http module can be used.

⁠Traffic accounting⁠

Account for traffic in realtime A realtime traffic and status code monitor solution for NGINX, which needs less memory and cpu than other realtime log analyzing solutions. Useful for traffic accounting based on NGINX config logic (by location / server / user-defined-variables).

⁠NChan⁠

A pub/sub module built in nginx Nchan is a scalable, flexible pub/sub server for the modern web, built as a module for the Nginx web server. It can be configured as a standalone server, or as a shim between your application and hundreds, thousands, or millions of live subscribers. It can buffer messages in memory, on-disk, or via Redis. All connections are handled asynchronously and distributed among any number of worker processes. It can also scale to many Nginx servers with Redis.

⁠ModSecurity⁠

The ModSecurity-nginx connector is the connection point between nginx and libmodsecurity (ModSecurity v3). Said another way, this project provides a communication channel between nginx and libmodsecurity. This connector is required to use LibModSecurity with nginx.

The ModSecurity-nginx connector takes the form of an nginx module. The module simply serves as a layer of communication between nginx and ModSecurity.

⁠OWASP Core Rulesets⁠

The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts.

⁠Upload Progress⁠

Add file upload progress support in nginx. Using https://github.com/dstroma/nginx-upload-progress-module⁠ as https://github.com/masterzen/nginx-upload-progress-module⁠ is not patched

⁠Headers More module⁠

Set and clear input and output headers...more than "add"!

⁠Dynamic Upstream⁠

ngx_dynamic_upstream is the module for operating upstreams dynamically with HTTP APIs such as ngx_http_upstream_conf.

⁠Status Module⁠

This module will help monitor running status of Nginx.

It can provide running status information of Nginx. The information is divided into different zones, and each zone is independent. The status information is about connections, requests, response status codes, input and output flows, rt, and upstreams. It shows all the results by default, and can be set to show part of them by specifying zones.

⁠Others

⁠ACME⁠

Installed ACME.sh script to autogenerate SSL for using letsencrypt or equivalent.

⁠Auto Reload

Auto reloads nginx config when it detects changes in the same. It will only reload if the changes are valid.

NOTE Upon container start/restart, if the config is invalid, then the service will not start!

⁠nginx-ctl

This is a helper utility built into nginx which helps in management and maintainance. To run these commands you must ssh into the container and run them. Ideally all the commands must be run as user tundra, but the script is smart enough to ensure correct permissions are maintained.

⁠initialize

This is an internal method and should not be called manually. It ensures all files and folders are available for nginx to run.

⁠configure

This is an internal method called at boot. Should not called manually. This function generates default configuration for dynamic components such as IP whitelisting, mod security config etc.

⁠reload

nginx-ctl reload

This will test the current nginx configuration and perform a reload if the configuration is valid. This is called by the auto reload script.

⁠add-site

This will create a new site config (if site is not present already) with some default values. The configuration file can be found in /etc/nginx/sites.d/DOMAIN.conf where DOMAIN is the first domain name passed as argument.

⁠disable-site

This will disable the site. Basically it renames the configuration file from DOMAIN.conf to DOMAIN.conf.disabled and then calls the reload function.

⁠enable-site

This will enable a site which has been disabled. Basically rename a site from DOMAIN.conf.disabled to DOMAIN.conf and call the reload function.

⁠list-sites

This will list all sites currently configured (both enabled and disabled)

⁠ENV Variables

@TODO - To be updated.

⁠MAXMIND_KEY

This is the license key provided by maxmind site to download updates for GeoIP2 database. Defaults to null.

⁠MAXMIND_VERSION

The version to download. Defaults to null. Accepted values:

• GeoIP2Lite-City
• GeoIP2Lite-Country
• GeoIP2-City
• GeoIP2-Country

⁠SSL_KEY_LENGTH

The key length to be used to generate SSL certificate. Defaults to 4096bit key

⁠ACME_ACCOUNT_EMAIL

The email id to be used by ACME to register and generate SSL certificates. Defaults to null

⁠ACME_SSL_CA

The certificate authority to use to generate the certificate. Defaults to letsencrypt. See ACME⁠ documentation for possible options.

⁠Configuring

By default, a base nginx config file is created with following dynamic modules enabled:

• Nginx upstream jdomain
• Traffic Accounting

The other modules are disabled/not loaded by default. To enable

• GeoIP2 - ENV variables MAXMIND_KEY and MAXMIND_VERSION needs to be set
• Fancy Index - This can be enabled on a site level. Follow sample template provided in templates folder
• NChan - This can be enabled on a site level. Follow sample template provided in templates folder
• ModSecurity - This can be enabled on a site level. Follow sample template provided in templates folder
• Upload Progress - This can be enabled on a site