--- 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`).
2. Search for duplicate blocks: `grep -rn "upstream xyz" /etc/nginx/`.
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;`.
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).
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'`.
2. Write PID to file: `echo > /var/run/nginx.pid`.
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.