major-ai-skills/skills/nginx/gpt.md

Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.

---

title: "Nginx High-Performance Reverse Proxy AI Skill Guide (GPT & Codex)"
description: "Comprehensive operational skill specification for OpenAI GPT and Codex to automate, script, troubleshoot, and optimize Nginx configurations, Jinja2 templating, Docker reverse proxies, and CI/CD validation."
category: "High-Performance HTTP Server & Reverse Proxy"
tags: ["nginx", "jinja2-templating", "docker-nginx", "reverse-proxy", "gpt-codex", "devops-automation"]
---


# Nginx High-Performance Reverse Proxy AI Skill Guide (GPT & Codex)

## Overview & Engine Architecture
Nginx is the de facto standard for cloud ingress, API gateways, and multi-tenant web routing. GPT/Codex acts as a Principal DevOps Automation Engineer and Infrastructure Architect, delivering **programmatic Nginx config generators (Jinja2/Python)**, **Docker/Kubernetes Ingress configurations**, **load testing automation scripts**, and **CI/CD syntax verification pipelines**.

### Architecture & Automated Infrastructure Stack

```
┌─────────────────────────────────────────────────────────────┐
│                 Nginx Automation Platform                   │
│                                                             │
│  Configuration Generation Engine                            │
│  ├── Python / Jinja2 Dynamic Virtual Host Compiler          │
│  ├── Multi-Tenant SSL SNI Routing & Upstream Slicing        │
│  └── Automated TLS Certbot Lifecycle Scripts                │
│                                                             │
│  Deployment & Container Runtime                             │
│  ├── Containerized Ingress (`nginx:alpine` Docker Base)     │
│  ├── CI/CD Config Linting & Zero-Downtime Hot Reload        │
│  └── Prometheus / OpenTelemetry Nginx Exporter Metrics      │
└─────────────────────────────────────────────────────────────┘
```

---


## Operational Capabilities & Agent Directives

1. **Dynamic Virtual Host Generation**: Author Python scripts using `jinja2` to render validated Nginx server blocks from database records or JSON service definitions.
2. **Containerized Ingress Architecture**: Build production Docker Compose and Dockerfile architectures pairing Nginx with Node.js/Python backend containers via internal Docker network bridge aliases.
3. **Automated CI/CD Validation**: Construct automated GitHub Actions / GitLab CI workflows to execute `nginx -t` inside a containerized linter before merging pull requests.
4. **Advanced Routing & Splitting**: Script A/B canary testing splits (`split_clients`) and geo-targeted routing rules.

---


## Production Python Automation: Dynamic Nginx VHost Generator (Jinja2)

Save this script as `generate_vhost.py` to programmatically render, validate, and deploy isolated Nginx configuration blocks:

```python
"""
Automated Nginx Virtual Host Generator (Jinja2)
Generates validated Nginx reverse proxy configurations from service specs.
"""

import sys
import os
import subprocess
from jinja2 import Template

VHOST_TEMPLATE = """
# Auto-generated Nginx Configuration for {{ service_name }}
upstream upstream_{{ service_slug }} {
    {% for server in backend_servers %}
    server {{ server }};
    {% endfor %}
    keepalive 16;
}

server {
    listen 80;
    server_name {{ domain }};

    location / {
        proxy_pass http://upstream_{{ service_slug }};
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_connect_timeout {{ timeout_sec }}s;
        proxy_read_timeout {{ timeout_sec }}s;
    }
}
"""

def generate_vhost(service_name: str, domain: str, backends: list, output_dir: str = "/etc/nginx/conf.d", timeout: int = 60):
    slug = service_name.lower().replace(" ", "_")
    template = Template(VHOST_TEMPLATE)
    rendered_config = template.render(
        service_name=service_name,
        service_slug=slug,
        domain=domain,
        backend_servers=backends,
        timeout_sec=timeout
    )

    os.makedirs(output_dir, exist_ok=True)
    out_file = os.path.join(output_dir, f"{slug}.conf")
    with open(out_file, "w", encoding="utf-8") as f:
        f.write(rendered_config.strip() + "\n")

    print(f"Rendered configuration to: {out_file}")

    # Validate syntax if running with local nginx binary
    try:
        check = subprocess.run(["nginx", "-t"], capture_output=True, text=True)
        if check.returncode == 0:
            print("Nginx syntax validation passed. Reloading...")
            subprocess.run(["nginx", "-s", "reload"])
        else:
            print(f"Syntax validation failed:\n{check.stderr}")
    except FileNotFoundError:
        print("Nginx binary not found in local path (skipping live reload).")

if __name__ == "__main__":
    generate_vhost(
        service_name="Billing Microservice",
        domain="billing.internal.io",
        backends=["127.0.0.1:5001", "127.0.0.1:5002"],
        output_dir="C:/Temp/nginx_conf"
    )
```

---


## Technical Troubleshooting Matrix

| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **`nginx: [emerg] duplicate upstream "xyz"`** | Multiple configuration files define the same `upstream` block name across `/etc/nginx/conf.d/`. | 1. Ensure upstream names include unique service slugs (e.g. `upstream_serviceA`).<br>2. Search for duplicate blocks: `grep -rn "upstream xyz" /etc/nginx/`.<br>3. Remove redundant `.conf` files. |
| **`nginx: [emerg] host not found in upstream` in Docker** | Nginx started before the target container host was reachable on the internal Docker network. | 1. Use dynamic DNS resolver in Nginx: `resolver 127.0.0.11 valid=10s;`.<br>2. Define upstream target as a variable: `set $upstream_target http://api:8080; proxy_pass $upstream_target;`. |
| **Large File Downloads Interrupted at Exactly 1GB** | `proxy_max_temp_file_size` exceeded while buffering large files to local disk. | 1. In location block, set: `proxy_max_temp_file_size 0;` (disables disk buffering).<br>2. Set `proxy_buffering off;` for direct streaming responses. |
| **Hot Reload Drops Connections (`nginx: [error] invalid PID`)** | Master PID file corrupted or previous master process terminated uncleanly. | 1. Find actual master process PID: `ps aux \| grep 'nginx: master'`.<br>2. Write PID to file: `echo <PID> > /var/run/nginx.pid`.<br>3. Trigger reload: `nginx -s reload`. |

---


## Command Line Syntax & Batch Processing

```bash
# Test Configuration Inside Docker Container Before Deployment
docker run --rm -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro nginx:alpine nginx -t

# Perform Zero-Downtime Reload Inside Docker Compose
docker compose exec nginx nginx -s reload
```

### Essential File Locations
- **Debian / Ubuntu Conf Dir**: `/etc/nginx/sites-available/` & `/etc/nginx/sites-enabled/`
- **RHEL / Alpine Conf Dir**: `/etc/nginx/conf.d/*.conf`
- **Nginx PID File**: `/var/run/nginx.pid`

---


## Agent Operational Directive
> **MANDATORY**: In containerized Docker/Kubernetes environments, resolve upstream services dynamically using internal DNS resolvers (`resolver 127.0.0.11;`) to prevent Nginx startup crashes when downstream services are booting.