dersni/nginx-ui-geoip2 repository overview

⁠Nginx UI with GeoIP2

A Docker image based on the official Nginx UI container with the GeoIP2 HTTP and Stream modules compiled and included.

The image tracks the latest stable Nginx UI release and automatically rebuilds the GeoIP2 modules against the exact Nginx version provided by the upstream Nginx UI Docker image.

⁠Features

• Based on uozi/nginx-ui:latest

• GeoIP2 HTTP module

• GeoIP2 Stream module

• MaxMind DB runtime library included

• Modules compiled against the Nginx version contained in the upstream image

• Automatic ABI compatibility test during the Docker build

• Multi-platform images for:

  • linux/amd64
  • linux/arm64

• Published to Docker Hub and GitHub Container Registry

• Automatic tracking of new Nginx UI releases

⁠Image Tags

Images follow the version of the upstream Nginx UI release.

For example, for Nginx UI v2.5.9 the following tags are published:

latest
v2
v2.5
v2.5.9

⁠Tag behavior

For production environments, an exact version tag such as v2.5.9 can be used if automatic upgrades are not desired.

⁠Docker Hub

docker pull dersni/nginx-ui-geoip2:latest

⁠GitHub Container Registry

docker pull ghcr.io/DjSni/nginx-ui-geoip2:latest

⁠Docker Compose

services:
  nginx-ui:
    image: dersni/nginx-ui-geoip2:latest
    container_name: nginx-ui

    restart: always

    environment:
      - TZ=Europe/Berlin

    volumes:
      - ./nginx:/etc/nginx
      - ./nginx-ui:/etc/nginx-ui
      - ./www:/var/www

      # Optional MaxMind GeoIP2 databases
      - ./geoip:/usr/share/GeoIP:ro

      # Optional: required for Nginx UI Docker integration
      - /var/run/docker.sock:/var/run/docker.sock

    ports:
      - "80:80"
      - "443:443"

⁠Included Modules

The following dynamic Nginx modules are included:

/usr/lib/nginx/modules/ngx_http_geoip2_module.so
/usr/lib/nginx/modules/ngx_stream_geoip2_module.so

The modules are not automatically enabled.

This allows existing Nginx UI installations to decide whether the HTTP module, Stream module, or both modules should be loaded.

⁠Enable GeoIP2

Add the required modules at the beginning of /etc/nginx/nginx.conf, before the events, http, or stream blocks.

⁠HTTP only

load_module /usr/lib/nginx/modules/ngx_http_geoip2_module.so;

⁠HTTP and Stream

load_module /usr/lib/nginx/modules/ngx_http_geoip2_module.so;
load_module /usr/lib/nginx/modules/ngx_stream_geoip2_module.so;

Example:

load_module /usr/lib/nginx/modules/ngx_http_geoip2_module.so;
load_module /usr/lib/nginx/modules/ngx_stream_geoip2_module.so;

user nginx;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    # ...
}

stream {
    # ...
}

⁠MaxMind Database

GeoIP2 requires a compatible MaxMind database such as GeoLite2 Country or GeoLite2 City.

The databases are not included in this image.

A common setup is to mount them into:

/usr/share/GeoIP/

Example:

volumes:
  - ./geoip:/usr/share/GeoIP:ro

Example files:

/usr/share/GeoIP/GeoLite2-Country.mmdb
/usr/share/GeoIP/GeoLite2-City.mmdb

⁠Example Nginx Configuration

geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
    auto_reload 5m;

    $geoip2_country_code country iso_code;
    $geoip2_country_name country names en;
}

server {
    listen 443 ssl;
    server_name example.com;

    location / {
        add_header X-Country-Code $geoip2_country_code;
        add_header X-Country-Name $geoip2_country_name;

        proxy_pass http://backend;
    }
}

The client address defaults to $remote_addr.

When Nginx is running behind another trusted reverse proxy or CDN, configure the appropriate real-IP or GeoIP2 proxy settings before using the country information for access control.

⁠Verify the Installation

Check the Nginx version:

docker exec nginx-ui nginx -v

Check the installed modules:

docker exec nginx-ui ls -lah /usr/lib/nginx/modules/

Check module dependencies:

docker exec nginx-ui \
  ldd /usr/lib/nginx/modules/ngx_http_geoip2_module.so

Validate the Nginx configuration:

docker exec nginx-ui nginx -t

⁠Automatic Builds

The image is rebuilt automatically.

During every build:

1. The latest uozi/nginx-ui:latest image is pulled.
2. The Nginx version contained in that image is detected.
3. The matching Nginx source code is downloaded.
4. The latest nginx-geoip2 source revision is retrieved.
5. The HTTP and Stream GeoIP2 modules are compiled.
6. The modules are tested against the Nginx binary from Nginx UI.
7. The resulting multi-platform image is published to Docker Hub and GHCR.

This prevents a GeoIP2 module compiled for a different Nginx release from being published successfully.

⁠Updating

When using the latest tag:

docker compose pull
docker compose up -d

When using a fixed release:

image: dersni/nginx-ui-geoip2:v2.5.9

Change the version explicitly when you want to upgrade.

⁠Upstream Projects

This project builds on:

• Nginx UI by 0xJacky
• nginx-geoip2 by kraloveckey
• Nginx
• libmaxminddb / MaxMind DB

This project only adds the GeoIP2 modules and their required runtime dependency to the upstream Nginx UI Docker image.

⁠Disclaimer

This is an unofficial community image and is not affiliated with or endorsed by the Nginx UI, Nginx, or MaxMind projects.

The underlying software remains subject to the licenses and terms of the respective upstream projects.