qida/nginx repository overview

⁠Nginx with GeoIP2 Module — Docker Image Documentation

⁠Overview

This Docker image is built on the official nginx:latest base image and extends it with the dynamic GeoIP2 module (ngx_http_geoip2_module), enabling real-time geolocation lookups of incoming client IP addresses using MaxMind GeoIP2 databases. It is suitable for scenarios that require IP-based geolocation, access control, traffic analysis, or region-specific content delivery.

⁠Build Process

1. Base Image: Uses the official nginx:latest image as the runtime foundation.
2. Build Dependencies: Installs compilation toolchain and GeoIP2 development libraries, including build-essential, libpcre2-dev, zlib1g-dev, libssl-dev, libmaxminddb-dev, and mmdb-bin, then cleans up the apt cache to reduce image size.
3. Source Download: Automatically detects the installed Nginx version, downloads the matching Nginx source tarball, and fetches the ngx_http_geoip2_module source from its GitHub repository.
4. Dynamic Module Compilation: Configures Nginx with --with-compat and the GeoIP2 dynamic module, then runs make modules to compile the module as a loadable .so file.
5. Module Installation: Copies the compiled ngx_http_geoip2_module.so into /etc/nginx/modules/ and removes temporary archives to keep the image lean.

⁠GeoIP2 Databases

The following MaxMind GeoIP2 database files are copied into /etc/nginx/geoip2/:

These databases can be referenced in nginx.conf via the geoip2 directive to map client IPs to country, city, and ASN data.

⁠Nginx Configuration Highlights

The bundled nginx.conf (/etc/nginx/nginx.conf) includes the following key settings:

• Worker Processes: Set to auto to match the number of CPU cores; worker_connections is 1024.
• Server Tokens Disabled: server_tokens off hides the Nginx version for security.
• Gzip Compression: Enabled with compression level 2, minimum length 1024 bytes, covering common text-based MIME types.
• Upload Limit: client_max_body_size 5G allows large file uploads.
• Access Control: The default server on port 80 (server_name _) returns 403 for all requests, forcing access via configured domain names/virtual hosts.
• Virtual Hosts: Additional HTTP server configurations can be placed in /etc/nginx/conf.d/*.conf.
• TCP Stream Forwarding: A stream block includes /etc/nginx/conf.d/*.stream, enabling raw TCP proxying (e.g., for non-HTTP protocols).
• Logging: Combined access log format with X-Forwarded-For support; stream access logging is disabled.

⁠Exposed Ports & Runtime

• Exposed Ports: 80 (HTTP) and 443 (HTTPS).
• Default Command: nginx -g 'daemon off;' — runs Nginx in the foreground, as required by Docker.

⁠Usage Notes

• Place custom virtual host configs in /etc/nginx/conf.d/ and TCP stream configs in /etc/nginx/conf.d/ with a .stream extension.

• The GeoIP2 module is compiled and installed in /etc/nginx/modules/, but it is not loaded by the default nginx.conf. You must manually add the load_module directive at the top level and reference a GeoIP2 database inside the http block (e.g., in /etc/nginx/conf.d/ or by editing nginx.conf) to activate it:

  load_module modules/ngx_http_geoip2_module.so;
  
  http {
      geoip2 /etc/nginx/geoip2/GeoLite2-City.mmdb {
          $geoip2_country_code country iso_code;
          $geoip2_city_name city names en;
      }
  }
  

  Copy

• Keep the GeoIP2 databases up to date by replacing the .mmdb files; they are not automatically refreshed.