### Docker Container Setup with Fractional CPU Limit

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

Run a Docker container with a fractional CPU limit (e.g., 0.5) and enable worker process autotuning. This example illustrates how the script calculates the number of worker processes by rounding up the fractional CPU allocation.

```bash
docker run --cpus=0.5 \
           -e NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE=1 \
           nginx:latest
```

--------------------------------

### Rendered Nginx Configuration Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

The result of processing the example Nginx template with specific environment variables set. This shows how placeholders are replaced with actual values.

```nginx
upstream api {
    server api.local:8080;
}
```

--------------------------------

### Example Nginx Configuration Template

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

An example of an Nginx configuration template file that includes placeholders for environment variables like NGINX_LOCAL_RESOLVERS, BACKEND_HOST, and BACKEND_PORT.

```nginx
upstream api {
    server ${API_SERVER}:${API_PORT};
}
```

--------------------------------

### Custom Entrypoint Hook Script for Nginx

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

This shell script is an example of a custom entrypoint hook for Nginx. It prints messages indicating the start and completion of custom setup actions.

```bash
#!/bin/sh
echo "Custom setup running..."
mkdir -p /var/www/custom
echo "Setup complete"
exit 0
```

--------------------------------

### Entrypoint Script Header and Setup

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

This snippet includes the shebang, vim modeline, error handling settings, locale configuration, and path setup for the script. It also includes a check to exit if the autotune environment variable is not set.

```bash
#!/bin/sh
# vim:sw=2:ts=2:sts:et

set -eu

LC_ALL=C
ME=$(basename "$0")
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

[ "${NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE:-}" ] || exit 0

touch /etc/nginx/nginx.conf 2>/dev/null || {
    echo >&2 "$ME: error: can not modify /etc/nginx/nginx.conf";
    exit 0;
}

# Helper functions for CPU detection...
# Main detection logic...
```

--------------------------------

### Custom Module Prebuild Script

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

Provide a custom shell script in modules/<module-name>/prebuild to execute custom setup commands before module compilation. This example shows a simple echo statement and successful exit.

```bash
#!/bin/sh
# Custom setup before build
echo "Configuring module..."
exit 0
```

--------------------------------

### Envsubst Command Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

A basic example of the envsubst command, showing how it substitutes variables from the environment into an input file to produce an output file. It highlights the syntax for variable references.

```bash
envsubst '$VAR1 $VAR2 $VAR3' < input.txt > output.txt
```

--------------------------------

### Docker Compose Configuration for Nginx

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/configuration.md

A comprehensive Docker Compose example showcasing the setup of Nginx with various environment variables, volume mounts for templates and hooks, and port mappings.

```yaml
version: '3.8'

services:
  nginx:
    image: nginx:latest
    environment:
      NGINX_ENTRYPOINT_QUIET_LOGS: "1"
      NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE: "1"
      NGINX_ENTRYPOINT_LOCAL_RESOLVERS: "1"
      NGINX_ENVSUBST_FILTER: "NGINX_|BACKEND_"
      BACKEND_SERVER: "app:3000"
      BACKEND_PORT: "8080"
    volumes:
      - ./templates:/etc/nginx/templates:ro
      - ./hooks:/docker-entrypoint.d/:ro
    ports:
      - "80:80"
      - "443:443"
```

--------------------------------

### Create Custom Module Prebuild Script

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Creates a 'prebuild' executable shell script for custom module setup. This script allows for complex build configurations or installation of specific tools before the main module build process.

```bash
cat > prebuild << 'EOF'
#!/bin/sh

# Custom build setup
echo "Building with custom configuration..."

EOF

```

--------------------------------

### Test Module Functionality in Container

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Starts an Nginx container, tests its configuration, lists modules, and then cleans up. This is a comprehensive check for module installation and Nginx service status.

```bash
docker run -d --name nginx-test nginx-lua:latest

# Check module is loaded
docker exec nginx-test \
    nginx -t

# Check in running container
docker exec nginx-test \
    ls -la /etc/nginx/modules/

docker rm -f nginx-test
```

--------------------------------

### Building Nginx with Custom Modules (Lua Example)

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/image-variants.md

Demonstrates how to build a custom Nginx Docker image with specific modules enabled, such as Lua and NDK.

```bash
docker build --build-arg ENABLED_MODULES="lua ndk" -t nginx-lua:latest \
    -f modules/Dockerfile .
```

--------------------------------

### Development: Quick Proxy Setup

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/README.md

Run a quick Nginx proxy for local development. Mounts local templates and sets backend host and port environment variables.

```bash
docker run -p 80:80 \
  -e BACKEND_HOST=localhost \
  -e BACKEND_PORT=3000 \
  -v $(pwd)/templates:/etc/nginx/templates:ro \
  nginx:latest
```

--------------------------------

### Docker Compose Service Discovery Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-15-resolvers.md

Illustrates how to use the resolver directive with a service name exposed by Docker Compose for proxying.

```bash
docker-compose up
# Creates "app" service accessible at "app" hostname

# In nginx config:
resolver ${NGINX_LOCAL_RESOLVERS};
location / {
    proxy_pass http://app:3000;  # Hostname resolved via resolver
}
```

--------------------------------

### Locale and PATH Setup

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-15-resolvers.md

Ensures predictable behavior of commands like awk by setting LC_ALL to C and defines standard system paths for command execution.

```bash
LC_ALL=C
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```

--------------------------------

### Logging with Verbose Output

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

This example shows the default logging behavior of the 20-envsubst-on-templates.sh script, indicating which template is being processed and its output file.

```bash
# With logging (default)
20-envsubst-on-templates.sh: Running envsubst on /etc/nginx/templates/config.template to /etc/nginx/conf.d/config
```

--------------------------------

### Nginx OTEL Configuration Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/image-variants.md

Example Nginx configuration for enabling OpenTelemetry instrumentation. This snippet shows how to load the OTEL module and configure an exporter, typically used for distributed tracing.

```nginx
load_module modules/ngx_otel_module.so;

opentelemetry {
    exporter jaeger {
        endpoint http://jaeger:14250;
    }
}

server {
    listen 80;
    otel_trace on;
    
    location / {
        proxy_pass http://backend;
    }
}
```

--------------------------------

### Example: Automatic IPv6 Enablement

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-10-ipv6.md

Demonstrates running the Nginx Docker container with default settings. The entrypoint script automatically detects and enables IPv6 listening if conditions are met.

```bash
docker run -d nginx:latest

```

--------------------------------

### Append Stream Block Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

An example of the content that would be appended to the Nginx configuration file when a new stream block is added.

```nginx
# added by 20-envsubst-on-templates.sh on 2026-06-01 12:00:00 UTC
stream {
  include /etc/nginx/stream-conf.d/*.conf;
}
```

--------------------------------

### Rendered HTTP Configuration Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

The resulting Nginx configuration file after environment variables from the Docker run command have been substituted into the template.

```nginx
server {
    listen 80;
    
    location / {
        proxy_pass http://api.local:8080;
    }
}
```

--------------------------------

### Install Compiled Modules (Alpine)

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Installs the compiled module packages (.apk files) into the runtime Nginx image. This step ensures that the modules are available for Nginx to load.

```dockerfile
apk add --virtual .nginx-modules \
    /build/packages/alpine/*.apk
```

--------------------------------

### Build Nginx from a Specific Base Image with Modules

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

Specify a base Nginx image using NGINX_FROM_IMAGE and list modules to build with ENABLED_MODULES. This example builds a stable-alpine Nginx with the brotli module.

```bash
docker build --build-arg NGINX_FROM_IMAGE="nginx:stable-alpine" \
  --build-arg ENABLED_MODULES="brotli" \
  -t nginx-stable-brotli:latest \
  -f modules/Dockerfile.alpine .
```

--------------------------------

### Run Default Nginx Container

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Starts a detached Nginx container listening on port 80. This is the simplest way to get Nginx running with its default configuration.

```bash
docker run -d -p 80:80 nginx:latest
```

--------------------------------

### Nginx Configuration with Tuned Worker Processes

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

Example of `nginx.conf` after the entrypoint script has tuned `worker_processes` to match the container's CPU limit. This ensures efficient resource utilization.

```nginx
# Commented out by 30-tune-worker-processes.sh on 2026-06-01 14:30:45 UTC
# worker_processes auto;
worker_processes 4;
```

--------------------------------

### HTTP Template Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

An example of an HTTP upstream template that uses environment variables for host and port. This template is processed by envsubst to generate a final Nginx configuration.

```nginx
upstream api_upstream {
    server ${API_HOST}:${API_PORT};
}
```

--------------------------------

### Logging with Quiet Mode

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

This example demonstrates the quiet logging mode enabled by setting NGINX_ENTRYPOINT_QUIET_LOGS=1. In this mode, the script produces no output during template processing.

```bash
# With NGINX_ENTRYPOINT_QUIET_LOGS=1
# (no output)
```

--------------------------------

### Docker Run Command for HTTP Template

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

Example command to run an Nginx container, mounting a local directory of templates and setting environment variables for substitution.

```bash
docker run -v /path/to/templates:/etc/nginx/templates:ro \
           -e BACKEND_HOST=api.local \
           -e BACKEND_PORT=8080 \
           nginx:latest
```

--------------------------------

### Running Nginx Container with Stable Alpine Slim Tag

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Starts a container using the 'nginx:stable-alpine-slim' tag, which provides a stable, minimal, and secure Nginx image. Ideal for security-sensitive deployments.

```bash
docker run nginx:stable-alpine-slim
```

--------------------------------

### Nginx .envsh Hook Script Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-hooks.md

This .envsh script example shows how to extract nameservers from /etc/resolv.conf and export them as an environment variable. Use .envsh scripts when you need to configure environment variables that should persist across subsequent hooks and the main Nginx process.

```bash
#!/bin/sh
# 15-local-resolvers.envsh
# Extract nameservers from /etc/resolv.conf and export as env var
set -eu

[ "${NGINX_ENTRYPOINT_LOCAL_RESOLVERS:-}" ] || return 0

NGINX_LOCAL_RESOLVERS=$(awk 'BEGIN{ORS=" "} $1=="nameserver" {if ($2 ~ ":") {print "["$2"]"} else {print $2}}' /etc/resolv.conf)
NGINX_LOCAL_RESOLVERS="${NGINX_LOCAL_RESOLVERS% }"

export NGINX_LOCAL_RESOLVERS

```

--------------------------------

### Stream Template Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

An example of a stream template for DNS resolution. It defines an upstream server group and a UDP server listening on port 53, proxying to the upstream. Environment variables are used for DNS server addresses.

```nginx
upstream dns_upstream {
    server ${DNS_SERVER1}:53;
    server ${DNS_SERVER2}:53;
}

server {
    listen 53 udp;
    proxy_pass dns_upstream;
}
```

--------------------------------

### Run Nginx with Environment Variable Templates

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Starts an Nginx container that uses a configuration template with environment variables for dynamic configuration. The template is mounted from the host, and variables like BACKEND_HOST and BACKEND_PORT are substituted at runtime.

```bash
docker run -d -p 80:80 \
  -v $(pwd)/templates:/etc/nginx/templates:ro \
  -e BACKEND_HOST=app.local \
  -e BACKEND_PORT=3000 \
  nginx:latest
```

--------------------------------

### Run Nginx as Load Balancer for Multiple Backends

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Starts an Nginx container configured for load balancing across multiple backend servers. Environment variables specify the backend server addresses and port, with the configuration template mounted from the host.

```bash
docker run -d -p 80:80 \
  -v $(pwd)/templates:/etc/nginx/templates:ro \
  -e APP_SERVER_1=app1.internal \
  -e APP_SERVER_2=app2.internal \
  -e APP_SERVER_3=app3.internal \
  -e APP_PORT=3000 \
  nginx:latest
```

--------------------------------

### Nginx Template File with Local Resolver

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-15-resolvers.md

An example Nginx template file demonstrating how to use the NGINX_LOCAL_RESOLVERS variable for the resolver directive.

```nginx
upstream backend {
    server api.internal:8080;
    resolver ${NGINX_LOCAL_RESOLVERS};
}
```

--------------------------------

### Lua Script Example for Nginx Handler

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

A simple Lua script that outputs 'Hello from Lua!' when executed by Nginx. This script is intended to be used with the 'content_by_lua_file' directive.

```lua
ngx.say("Hello from Lua!")
```

--------------------------------

### Module Build Dependencies

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

List package names for build dependencies in the modules/<module-name>/build-deps file. This example shows dependencies for Alpine or Debian-based systems.

```text
make gcc openssl-dev
```

--------------------------------

### Nginx .sh Hook Script Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-hooks.md

This .sh script example demonstrates how to modify Nginx configuration files. It enables IPv6 listening on port 80 by default. Use .sh scripts for filesystem modifications or tasks that don't require environment variable persistence.

```bash
#!/bin/sh
# 10-listen-on-ipv6-by-default.sh
# Makes configuration modifications to enable IPv6 listening
set -e

if [ ! -f "/etc/nginx/conf.d/default.conf" ]; then
    exit 0
fi

# Enable IPv6 on port 80
sed -i 's/listen       80;/listen       80;\n    listen  [::]:80;/' \
    /etc/nginx/conf.d/default.conf

```

--------------------------------

### Running Nginx Container with Specific Version Tag

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Starts a container using a specific version tag like 'nginx:1.30.2'. This is useful for production environments requiring a known, stable version.

```bash
docker run nginx:1.30.2
```

--------------------------------

### Nginx Resolver Configuration Template

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-15-resolvers.md

Example Nginx configuration template demonstrating how to use the exported NGINX_LOCAL_RESOLVERS variable in the resolver directive.

```nginx
# /etc/nginx/templates/resolvers.template
resolver ${NGINX_LOCAL_RESOLVERS} valid=10s;
```

--------------------------------

### Nginx HTTP Configuration Template Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

A basic Nginx server configuration template that uses environment variables for proxy pass. This demonstrates how templates are processed to generate final Nginx configuration files.

```nginx
server {
    listen 80;
    
    location / {
        proxy_pass http://${BACKEND_HOST}:${BACKEND_PORT};
    }
}
```

--------------------------------

### Docker Container Setup with CPU Limit

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

Run a Docker container with a specific CPU limit and enable worker process autotuning via an environment variable. This scenario demonstrates how the script detects and applies the CPU limit.

```bash
docker run --cpus=4 \
           -e NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE=1 \
           nginx:latest
```

--------------------------------

### Build Image with Pre-Packaged Lua and NDK Modules

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Builds a Docker image with the Lua and NDK modules pre-compiled and installed. This is a quick way to add scripting and extended functionality to Nginx.

```bash
docker build --build-arg ENABLED_MODULES="lua ndk" \
             -t my-nginx-with-lua:latest \
             -f modules/Dockerfile .

```

--------------------------------

### Nginx Image Filter Module Configuration

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/image-variants.md

Example of using the image filter module to resize images on the fly and set JPEG quality.

```nginx
location ~ /resize/(\d+)x(\d+)/(.+) {
    image_filter resize $1 $2;
    image_filter_jpeg_quality 90;
    proxy_pass http://storage/$3;
}
```

--------------------------------

### Run Nginx with Quiet Logs

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-hooks.md

Example of running the Nginx Docker container with quiet logs enabled. This suppresses most informational log messages from the entrypoint.

```bash
docker run -e NGINX_ENTRYPOINT_QUIET_LOGS=1 nginx:latest
```

--------------------------------

### Patch Source Code Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Applies a patch file to the source code. Ensure you are in the correct directory before applying the patch. The 'patch -p1' command is used to apply patches with a single leading directory component.

```bash
cd /build
curl -fL https://example.com/patch.diff | patch -p1

exit 0
EOF
chmod +x prebuild
```

--------------------------------

### List Available Modules in Container

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Lists all shared object (.so) files found in the Nginx modules directory within a Docker container. This helps confirm that modules were successfully installed.

```bash
docker run --rm nginx-lua:latest \
    find /etc/nginx/modules -name "*.so"
```

--------------------------------

### Setup Project Directory for Custom Nginx Module

Source: https://github.com/nginx/docker-nginx/blob/master/modules/README.md

Initializes the project workspace by creating a dedicated directory for the custom Nginx build configuration.

```bash
mkdir myapp-cache
cd myapp-cache
```

--------------------------------

### Run Nginx as Reverse Proxy to Single Backend

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Starts an Nginx container configured as a reverse proxy to a single backend service using environment variables for backend details. The configuration template is mounted from the host.

```bash
docker run -d -p 80:80 \
  -v $(pwd)/templates:/etc/nginx/templates:ro \
  -e BACKEND_HOST=api.example.com \
  -e BACKEND_PORT=8080 \
  nginx:latest
```

--------------------------------

### Example JSON Output of Docker Image Environment Variables

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Shows the expected JSON output when inspecting the environment variables of the 'nginx:latest' Docker image. This includes NGINX_VERSION, NJS_VERSION, NJS_RELEASE, and ACME_VERSION.

```json
[
  "NGINX_VERSION=1.31.1",
  "NJS_VERSION=0.9.9",
  "NJS_RELEASE=1~trixie",
  "ACME_VERSION=0.4.1"
]
```

--------------------------------

### Nginx Configuration with Auto Worker Processes

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

Example of `nginx.conf` using `worker_processes auto;` which, without the entrypoint script, would utilize all system CPUs, potentially leading to contention in limited environments.

```nginx
worker_processes auto;
```

--------------------------------

### Build with Multiple Base Images and Modules

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Demonstrates building Nginx images with specified modules and different base images (Debian, Alpine, Stable). Use `NGINX_FROM_IMAGE` to select the base, and `modules/Dockerfile.alpine` for Alpine builds.

```bash
# Debian-based
docker build --build-arg ENABLED_MODULES="lua" \
             --build-arg NGINX_FROM_IMAGE="nginx:latest" \
             -t nginx-lua:debian .

# Alpine-based
docker build --build-arg ENABLED_MODULES="lua" \
             --build-arg NGINX_FROM_IMAGE="nginx:alpine" \
             -f modules/Dockerfile.alpine \
             -t nginx-lua:alpine .

# Stable branch
docker build --build-arg ENABLED_MODULES="lua" \
             --build-arg NGINX_FROM_IMAGE="nginx:stable" \
             -t nginx-lua:stable .
```

--------------------------------

### Docker Container Setup with Read-Only Filesystem

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

Attempt to run a Docker container with a read-only filesystem and worker process autotuning enabled. This demonstrates the script's graceful failure mechanism when it cannot modify `nginx.conf`.

```bash
docker run --read-only \
           -e NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE=1 \
           nginx:latest
```

--------------------------------

### Install Build Dependencies (Alpine)

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Installs all packages listed in the 'build-deps' file as virtual dependencies, allowing for easy cleanup after the build process.

```dockerfile
apk add --virtual .build-deps $(cat build-deps)
```

--------------------------------

### Envsubst Whitelist Filter Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

This bash command demonstrates a method to create a whitelist of environment variables for envsubst using awk and printf. This approach filters variables based on a pattern, enhancing security and explicitness.

```bash
defined_envs=$(printf '${%s} ' $(awk "END { for (name in ENVIRON) 
    { print ( name ~ /${filter}/ ) ? name : "" } }" < /dev/null ))
```

--------------------------------

### Run Nginx with Read-Only Filesystem

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-10-ipv6.md

Demonstrates running an Nginx container with a read-only filesystem to test how the entrypoint script handles write restrictions.

```bash
docker run -d --read-only nginx:latest
```

--------------------------------

### Enable IPv6 Listening Logs

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-10-ipv6.md

Run an Nginx container to observe the default logging behavior of the entrypoint script, which indicates IPv6 listening is enabled.

```bash
docker run nginx:latest
```

--------------------------------

### Create Nginx Configuration Template Directory

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Prepares a directory on the host system to store Nginx configuration template files for use with environment variable substitution.

```bash
mkdir -p templates
```

--------------------------------

### Installing Specific Nginx Package Versions

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Installs Nginx and its modules using exact version specifications during the Docker image build process. This ensures reproducible builds with specific component versions.

```dockerfile
RUN apt-get install \
    nginx=${NGINX_VERSION}-${PKG_RELEASE} \
    nginx-module-njs=${NGINX_VERSION}+${NJS_VERSION}-${NJS_RELEASE} \
    nginx-module-acme=${NGINX_VERSION}+${ACME_VERSION}-${PKG_RELEASE} \
    ... 
```

--------------------------------

### Listing Installed Nginx Module Versions

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Finds and lists the base names of all shared object files (.so) in the /etc/nginx/modules directory within a running container. This helps identify installed Nginx modules.

```bash
# Check installed module versions
docker exec <container> find /etc/nginx/modules -name "*.so" -exec basename {} \;
```

--------------------------------

### Nginx XSLT Module Configuration

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/image-variants.md

Example of configuring the XSLT module to transform XML responses using a specified stylesheet.

```nginx
location /api/ {
    proxy_pass http://backend;
    xslt_stylesheet /etc/nginx/xslt/transform.xsl;
}
```

--------------------------------

### User-Modified Configuration Dockerfile

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-10-ipv6.md

Example of a custom Dockerfile that modifies the default Nginx configuration, showing how the entrypoint script detects changes.

```dockerfile
FROM nginx:latest
RUN echo 'custom content' >> /etc/nginx/conf.d/default.conf
```

--------------------------------

### Build with Module Dependencies

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Builds an Nginx image including modules that have dependencies on others. List all required modules, including their dependencies, in the `ENABLED_MODULES` argument.

```bash
docker build --build-arg ENABLED_MODULES="ndk lua headers-more" \
             -t nginx-full-modules:latest \
             -f modules/Dockerfile .
```

--------------------------------

### Nginx Configuration with Tuned Worker Processes (Manual Comparison)

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

Illustrates the resulting `nginx.conf` when the entrypoint script's auto-tuning is active, setting `worker_processes` to match the container's CPU limit, contrasting with the default 'auto' behavior.

```nginx
worker_processes 4;  # Matches container's CPU limit
```

--------------------------------

### Nginx njs JavaScript Module Example

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/image-variants.md

A simple njs module that handles HTTP requests and returns a 'Hello from njs!' message.

```javascript
export default {
    http_handler: function(r) {
        r.return(200, "Hello from njs!");
    }
};
```

--------------------------------

### Inject Local Nameservers into Resolver Directives

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/configuration.md

A template example demonstrating how to use the NGINX_LOCAL_RESOLVERS environment variable within an Nginx configuration template.

```nginx
# Template: /etc/nginx/templates/resolver.template
resolver ${NGINX_LOCAL_RESOLVERS};
```

--------------------------------

### Build Image with Multiple Pre-Packaged Modules

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Builds a Docker image with multiple pre-packaged modules (Lua, NDK, Brotli) enabled. Modules are specified as a space-separated list in the ENABLED_MODULES build argument.

```bash
docker build --build-arg ENABLED_MODULES="lua ndk brotli" \
             -t nginx-full:latest \
             -f modules/Dockerfile .

```

--------------------------------

### Static Resolver Configuration (Without Script)

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-15-resolvers.md

Manual configuration of the resolver IP address in Nginx, which is less portable than using the entrypoint script.

```bash
# User must manually set resolver in nginx config
resolver 127.0.0.11;
```

--------------------------------

### Production: Stable with Optimizations

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/README.md

Deploy a stable Nginx instance for production. Enables auto-tuning of worker processes, maps ports, and mounts configuration and HTML directories.

```bash
docker run -d \
  --cpus=4 \
  -e NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE=1 \
  -p 80:80 \
  -p 443:443 \
  -v $(pwd)/conf:/etc/nginx/conf.d:ro \
  -v $(pwd)/html:/usr/share/nginx/html:ro \
  nginx:stable
```

--------------------------------

### Echo Module Build Dependencies

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Lists the build dependencies required for the echo module. These are space-separated package names that will be installed in the build environment.

```text
make gcc

```

--------------------------------

### Nginx ACME Module Configuration

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/image-variants.md

Example of configuring Nginx to use the ACME module for automatic SSL certificate provisioning with Let's Encrypt.

```nginx
server {
    listen 443 ssl;
    server_name example.com;
    
    ssl_certificate /var/lib/nginx/acme/example.com.crt;
    ssl_certificate_key /var/lib/nginx/acme/example.com.key;
    
    acme on;
}
```

--------------------------------

### Build and Run Custom Nginx Image

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Builds a Docker image from a Dockerfile and then runs a container from that image, setting environment variables for backend configuration.

```bash
docker build -t my-nginx .
docker run -d -p 80:80 \
  -e BACKEND_HOST=backend \
  -e BACKEND_PORT=8080 \
  my-nginx
```

--------------------------------

### Build Custom Nginx Image with Modules

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Builds a Docker image with specified modules enabled. Use the ENABLE_MODULES build argument to list modules separated by spaces. The -f flag specifies the Dockerfile to use.

```bash
docker build --build-arg ENABLED_MODULES="mymodule" \
             -t nginx-mymodule:latest \
             -f modules/Dockerfile .
```

```bash
docker build --build-arg ENABLED_MODULES="lua ndk" \
             -f modules/Dockerfile.alpine \
             -t nginx-lua-alpine:latest .
```

--------------------------------

### Building a Test Docker Image

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Builds a Docker image for testing purposes using a specific tag, such as 'nginx:test'. This is done after regenerating Dockerfiles.

```bash
cd stable/debian
docker build -t nginx:test .
```

--------------------------------

### Run Nginx with Minimal Alpine Image

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Deploy Nginx using the smallest available Docker image variant for a reduced attack surface. Mounts custom configuration.

```bash
docker run -d -p 80:80 \
  -v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
  nginx:latest-alpine-slim
```

--------------------------------

### Get Cgroup V1 Path

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

Locates the cgroup path for a given controller type in a cgroup v1 hierarchy. Returns the full filesystem path if found.

```bash
get_cgroup_v1_path() {
  needle=$1  # "cpuset" or "cpu"
  # ... locates cgroup path in v1 hierarchy
  echo "$foundroot"
}
```

--------------------------------

### Nginx Entrypoint Script: 10-listen-on-ipv6-by-default.sh

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-10-ipv6.md

This script automatically configures IPv6 listening on port 80 if the system supports IPv6 and the default configuration is unmodified. It runs automatically during container startup.

```bash
#!/bin/sh
# vim:sw=4:ts=4:et

set -e

entrypoint_log() {
    if [ -z "${NGINX_ENTRYPOINT_QUIET_LOGS:-}" ]; then
        echo "$@"
    fi
}

# Core function: Modify /etc/nginx/conf.d/default.conf to add IPv6 listener

```

--------------------------------

### Get Cgroup V2 CPU Quota

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

Retrieves the CPU quota from cgroup v2. This function is used for cgroup v2 environments to determine CPU limits.

```bash
get_quota_v2() {
  cpuroot=$1
  ncpu=0
  
  [ -f "$cpuroot/cpu.max" ] || return 1
  
  cfs_quota=$( cut -d' ' -f 1 < "$cpuroot/cpu.max" )
  cfs_period=$( cut -d' ' -f 2 < "$cpuroot/cpu.max" )
  
  [ "$cfs_quota" = "max" ] && return 1
  [ "$cfs_period" = "0" ] && return 1
  
  ncpu=$( ceildiv "$cfs_quota" "$cfs_period" )
  [ "$ncpu" -gt 0 ] || return 1
  
  echo "$ncpu"
}
```

--------------------------------

### Execute Prebuild Script

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Runs a custom 'prebuild' script if it exists and is executable. This script can be used for tasks like patching sources or downloading additional files before compilation. It must exit with a status code of 0.

```bash
/build/modules/${module}/prebuild
```

--------------------------------

### Get Cgroup V1 CPU Quota

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

Retrieves the CPU quota from cgroup v1. Use this when working with cgroup v1 environments to determine CPU limits.

```bash
get_quota() {
  cpuroot=$1
  ncpu=0
  
  [ -f "$cpuroot/cpu.cfs_quota_us" ] || return 1
  [ -f "$cpuroot/cpu.cfs_period_us" ] || return 1
  
  cfs_quota=$( cat "$cpuroot/cpu.cfs_quota_us" )
  cfs_period=$( cat "$cpuroot/cpu.cfs_period_us" )
  
  [ "$cfs_quota" = "-1" ] && return 1
  [ "$cfs_period" = "0" ] && return 1
  
  ncpu=$( ceildiv "$cfs_quota" "$cfs_period" )
  [ "$ncpu" -gt 0 ] || return 1
  
  echo "$ncpu"
}
```

--------------------------------

### Kubernetes Secret for Nginx SSL Configuration

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

Example Kubernetes configuration demonstrating how to store sensitive Nginx configuration, like SSL keys, in a Secret and mount it to a Pod.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: nginx-config
type: Opaque
stringData:
  ssl_key: |
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----

---
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: nginx:latest
    volumeMounts:
    - name: ssl-config
      mountPath: /etc/nginx/ssl
      readOnly: true
  volumes:
  - name: ssl-config
    secret:
      secretName: nginx-config
```

--------------------------------

### Docker Run Command with Variable Filtering

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

Example Docker run command that sets environment variables and a filter for envsubst. This controls which variables are substituted in the Nginx templates.

```bash
docker run -e NGINX_ENVSUBST_FILTER='NGINX_|BACKEND_'
           -e NGINX_BACKEND_HOST=backend.local 
           -e BACKEND_PORT=8080 
           -e SECRET_KEY=topsecret123 
           nginx:latest
```

--------------------------------

### Backup Nginx Configuration with sed

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-30-workers.md

This command creates a backup of the Nginx configuration file before applying modifications using sed. The backup file will have a .bak extension.

```bash
sed -i.bak -r 's/.../'  /etc/nginx/nginx.conf
```

--------------------------------

### Get Cgroup V2 Path

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/api-reference.md

Locates the cgroup path in the cgroup v2 unified hierarchy. This function reads from /proc/self/ files and returns the full filesystem path if found.

```bash
get_cgroup_v2_path() {
  # ... locates cgroup path in v2 unified hierarchy
  echo "$foundroot"
}
```

--------------------------------

### Run Nginx with Let's Encrypt Configuration

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

This command runs an Nginx container with volumes mounted for templates, SSL certificates, and ACME challenges. It sets environment variables for domain and backend configuration.

```bash
docker run -d -p 80:80 -p 443:443 \
  -v $(pwd)/templates:/etc/nginx/templates:ro \
  -v $(pwd)/ssl:/etc/nginx/ssl:rw \
  -v $(pwd)/acme:/var/www/acme:rw \
  -e DOMAIN=example.com \
  -e BACKEND_HOST=backend.local \
  -e BACKEND_PORT=8080 \
  nginx:latest
```

--------------------------------

### Docker Run Command for Template Rendering

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/entrypoint-20-templates.md

This command demonstrates how to run an Nginx container, mounting a directory of templates and providing environment variables that will be substituted into those templates.

```bash
docker run -v /path/to/templates:/etc/nginx/templates:ro \
           -e API_HOST=api.local \
           -e API_PORT=8080 \
           -e DNS_SERVER1=8.8.8.8 \
           -e DNS_SERVER2=8.8.4.4 \
           nginx:latest
```

--------------------------------

### Manually Execute Nginx Entrypoint Script

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

After starting an interactive Nginx container session, this command manually executes the Docker entrypoint script. This is useful for debugging the entrypoint's behavior.

```bash
/docker-entrypoint.sh nginx
```

--------------------------------

### Run Nginx Interactively for Debugging Entrypoint

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

This command runs an Nginx container interactively, mounting necessary volumes and setting environment variables. It allows manual execution of the entrypoint script for debugging.

```bash
docker run -it \
  -v $(pwd)/templates:/etc/nginx/templates:ro \
  -e BACKEND_HOST=test \
  nginx:latest \
  /bin/sh
```

--------------------------------

### Run Minimal Alpine Nginx Image

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

This command runs a minimal Nginx container based on the Alpine Linux slim image. It maps host ports to container ports and mounts configuration and HTML directories.

```bash
docker run -d -p 80:80 \
  -v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
  -v $(pwd)/html:/usr/share/nginx/html:ro \
  nginx:latest-alpine-slim
```

--------------------------------

### Create Custom Module Build Dependencies File

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Creates the 'build-deps' file for a custom module, listing additional build dependencies like 'curl', 'openssl-dev', and 'pcre2-dev'. These are space-separated and will be installed during the build process.

```bash
echo "curl openssl-dev pcre2-dev" > build-deps

```

--------------------------------

### Custom Build: With Lua Scripting

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/README.md

Build a custom Nginx image with specific modules enabled, such as Lua and NDK. Uses a Dockerfile from a modules directory.

```bash
docker build --build-arg ENABLED_MODULES="lua ndk" \
  -t my-nginx-lua:latest \
  -f modules/Dockerfile .
```

--------------------------------

### Set Multiple Docker Environment Variables

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/configuration.md

Demonstrates setting multiple environment variables for Nginx configuration and other purposes when running a Docker container.

```bash
docker run \
  -e NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE=1 \
  -e NGINX_ENTRYPOINT_LOCAL_RESOLVERS=1 \
  -e BACKEND_SERVER=upstream.local \
  nginx:latest
```

--------------------------------

### Setting Nginx and Module Versions in Dockerfile

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/versions-and-releases.md

Defines environment variables for Nginx, NJS, ACME, and package release versions within a Dockerfile. These variables are used later to install specific package versions.

```dockerfile
FROM debian:trixie-slim
ENV NGINX_VERSION    1.30.2
ENV NJS_VERSION      0.9.9
ENV NJS_RELEASE      1~trixie
ENV ACME_VERSION     0.4.1
ENV PKG_RELEASE      1~trixie
ENV DYNPKG_RELEASE   1~trixie
```

--------------------------------

### Multi-Service Routing with Docker Compose

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/getting-started.md

This Docker Compose setup configures Nginx to route traffic to multiple backend services (API and Web). It uses environment variables to define service hosts and ports.

```yaml
version: '3.8'

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./templates:/etc/nginx/templates:ro
    environment:
      NGINX_ENVSUBST_FILTER: "SERVICE_"
      API_SERVICE_HOST: api
      API_SERVICE_PORT: "8080"
      WEB_SERVICE_HOST: web
      WEB_SERVICE_PORT: "3000"
    depends_on:
      - api
      - web
  
  api:
    image: my-api:latest
    expose:
      - "8080"
  
  web:
    image: my-web:latest
    expose:
      - "3000"
```

--------------------------------

### Troubleshoot Module Not Loading

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Provides steps to resolve 'Module not loading' errors in Nginx. This involves checking module file existence, verifying the `load_module` directive, and reloading Nginx.

```bash
# Error in nginx:
# [emerg] dlopen() "/etc/nginx/modules/..." failed

# Solution:
# 1. Verify module file exists: docker exec <container> ls /etc/nginx/modules/
# 2. Check nginx config has `load_module` directive
# 3. Reload nginx: docker exec <container> nginx -s reload
```

--------------------------------

### Build Alpine Image with Pre-Packaged Lua and NDK Modules

Source: https://github.com/nginx/docker-nginx/blob/master/_autodocs/module-system.md

Builds a Docker image using an Alpine base instead of Debian, including the Lua and NDK modules. This is useful for creating smaller, more optimized Nginx images.

```bash
docker build --build-arg ENABLED_MODULES="lua ndk" \
             -t my-nginx-with-lua:alpine \
             -f modules/Dockerfile.alpine .

```