DOCSEARCHbyAlgolia
Submit Docs

NGINX Docker Image Build Definitions

repository·master·Indexed 25 days ago

https://github.com/nginx/docker-nginx

Build definitions and source for the official NGINX Docker image. Includes instructions for extending images with third-party modules using the ENABLED_MODULES build argument, utilizing the pkg-oss repository for pre-packaged modules, and defining custom module build instructions for Debian and Alpine-based images.

Tokens
1.5K
Snippets
3
Records
9
Agent score
36%

What's inside docker-nginx

  3. Define a custom module build instruction

    master

    If a module is not available in pkg-oss, you can provide your own build instructions by creating a directory named after the module within your build context. The directory must follow this structure:

    • source: (Required) A file containing a URL to a zip/tarball of the module's source code.
    • build-deps: (Optional) A file specifying build dependencies available in Debian or Alpine repositories.
    • prebuild: (Optional) A shell script (must be executable via chmod +x) that runs after installing build-deps but before building the module. Use this to install additional dependencies. Note that dependencies installed via prebuild are not automatically copied to the final image; if building a library, build it statically.
    docker-nginx/modules $
└── echo
    ├── build-deps
    ├── prebuild
    └── source

  5. Build NGINX image with third-party modules

    master

    You can extend a mainline NGINX image with third-party modules using the provided Dockerfile. This works by specifying modules via the ENABLED_MODULES build argument. The build process will first look for local module definitions in the build context; if not found, it attempts to fetch them from the pkg-oss repository.

    Requirements:

    • Docker BuildKit is required. For Docker versions earlier than 23.0, enable it by setting the environment variable DOCKER_BUILDKIT=1.

    Build Arguments:

    • ENABLED_MODULES: A space-separated list of modules to include (e.g., ndk lua).
    • NGINX_FROM_IMAGE: Specifies the base NGINX image to use (e.g., nginx:stable). Defaults to the mainline image.

    Base OS Selection:

    • By default, the build uses a Debian-based image.
    • To use Alpine, use the -f Dockerfile.alpine flag during the build.

  6. Get support for NGINX core products

    master

    For questions regarding NGINX itself (rather than the Docker implementation), use the following resources:

    • Community Forum: Visit the NGINX Community Forum and check the Troubleshooting or How do I...? categories.
    • Official Documentation:
    • Mailing Lists: Contact the NGINX development team directly via the mailing lists at mailman.nginx.org.

  7. Use docker-compose with a custom (non-packaged) module

    master

    To build an NGINX image with a module not in pkg-oss (e.g., ngx_cache_purge), you must provide the source URL in the build context:

    1. Create a project directory.
    2. Download the module Dockerfile into a sub-directory (e.g., my-nginx/).
    3. Create a directory named after the module (e.g., my-nginx/cachepurge/).
    4. Create a source file inside that directory containing the URL to the module's source tarball.
    5. Configure docker-compose.yml to use the module name in ENABLED_MODULES.
    # 1. Setup directories
mkdir myapp-cache && cd myapp-cache
mkdir my-nginx

# 2. Get Dockerfile
curl -o my-nginx/Dockerfile https://raw.githubusercontent.com/nginx/docker-nginx/master/modules/Dockerfile

# 3. Provide custom module source
mkdir my-nginx/cachepurge
echo "https://github.com/FRiCKLE/ngx_cache_purge/archive/2.3.tar.gz" > my-nginx/cachepurge/source

# 4. Create docker-compose.yml
cat > docker-compose.yml << __EOF__
version: "3.3"
services:
  web:
    build:
      context: ./my-nginx/
      args:
        ENABLED_MODULES: cachepurge
    image: my-nginx-with-cachepurge:v1
    ports:
      - "80:8080"
__EOF__

# 5. Build and run
docker-compose up --build -d

  8. Use docker-compose with pre-packaged modules

    master

    To build and run an NGINX instance with modules already available in pkg-oss using docker-compose, follow these steps:

    1. Create a project directory.
    2. Download the module Dockerfile into a sub-directory (e.g., my-nginx/).
    3. Define the ENABLED_MODULES argument in your docker-compose.yml under the build section.
    version: "3.3"
services:
  web:
    build:
      context: ./my-nginx/
      args:
        ENABLED_MODULES: ndk lua
    image: my-nginx-with-lua:v1
    ports:
      - "80:8000"

  9. Available modules in pkg-oss

    master

    The following modules are available for direct use via the ENABLED_MODULES argument, as they are maintained in the pkg-oss repository:

    • auth-spnego (1.1.2-1)
    • brotli (1.0.0-1)
    • encrypted-session (0.09-1)
    • fips-check (0.1-1)
    • geoip (1.27.4-1)
    • geoip2 (3.4-1)
    • headers-more (0.37-1)
    • image-filter (1.27.4-1)
    • lua (0.10.28-1)
    • ndk (0.3.3-1)
    • njs (0.8.9-1)
    • otel (0.1.1-1)
    • passenger (6.0.26-1)
    • perl (1.27.4-1)
    • rtmp (1.2.2-1)
    • set-misc (0.33-1)
    • subs-filter (0.6.4-1)
    • xslt (1.27.4-1)