Nginx Documentation

A comprehensive guide to installing, configuring, and operating Nginx — a high-performance, event-driven web server and reverse proxy that powers a significant portion of the world's web infrastructure.

CLI-First Philosophy

This documentation is written for administrators who work in tmux, navigate with yazi, and build automation with bash. Every task is done from the terminal. No GUI required. Use opencode to pipe config files and log output for AI-assisted debugging and config generation.

---

What Nginx Does Well

Nginx excels at three things:

1. Static file delivery — extremely fast, low memory footprint
2. Reverse proxy — sitting in front of Node.js, PHP-FPM, Python apps, or upstream servers
3. Load balancing — distributing traffic across multiple backends

---

Learning Path

1. Foundations

Understand the server model, process architecture, file layout, and basic configuration syntax.

• Core Foundations — Architecture, installation, directory structure, and master process model
• Server Configuration — nginx.conf structure, server blocks, location blocks, and directives

2. Core Workflows

Layer	Module	Focus
Tune	Performance Optimization	Caching, compression, HTTP/2, worker tuning
Execute	PHP Integration	PHP-FPM pools, socket config, php.ini tuning
Protect	Security	TLS, security headers, IP access, rate limiting
Observe	Logging and Monitoring	Log formats, access/error logs, real-time analysis

3. Proxy & CDN

Connect Nginx to backends and Cloudflare for global delivery.

• Reverse Proxy & Load Balancing — Upstream blocks, proxy headers, health checks, load balancing strategies
• Cloudflare Integration — Real IP restoration, SSL modes, caching, edge config

4. Advanced & Reference

• Advanced Features — Rewrites, maps, streams, CLI management, bash automation, opencode workflows
• Troubleshooting & Maintenance — Errors, config validation, performance debugging, upgrades

5. Cheatsheets

Quick-reference cards for every Nginx operation — designed for fast lookup in a tmux session.

Cheatsheet	What It Covers
CLI Quick Reference	All CLI commands — service, config test, logs, diagnostics
Config Syntax Reference	nginx.conf directives, server blocks, location matching
Server Block Setup	Full workflow for adding new sites from CLI
PHP-FPM Tuning	Pool config, socket, php.ini, OPcache
Security Hardening	TLS, headers, IP rules, rate limiting
Performance Tuning	HTTP/2, caching, compression, worker tuning
Troubleshooting Matrix	Errors → root causes → exact fixes
Automation & Bash Scripts	Scripts, cron patterns, opencode AI workflows

---

Architecture at a Glance

Client Request
  └── Nginx Master Process (root, reads config)
       └── Worker Processes (nobody/www-data, handles connections)
            ├── Static files → served directly from disk
            ├── PHP → forwarded to PHP-FPM via socket/TCP
            └── Upstream apps → reverse proxied to backends

Request Flow

Internet → Cloudflare (optional) → Nginx Listener :80/:443
  └── server block match (by server_name)
       └── location block match (by URI pattern)
            ├── root/alias → static file
            ├── fastcgi_pass → PHP-FPM
            └── proxy_pass → upstream backend

---

Core File Paths

/etc/nginx/
├── nginx.conf              # Main config (worker count, events, includes)
├── conf.d/                 # Drop-in server block configs (*.conf auto-loaded)
├── sites-available/        # Site configs (Debian/Ubuntu pattern)
├── sites-enabled/          # Symlinks to sites-available (active sites)
├── snippets/               # Reusable config fragments (SSL, FastCGI params)
├── fastcgi_params          # Default FastCGI parameter set
├── fastcgi.conf            # Extended FastCGI params (includes SCRIPT_FILENAME)
├── mime.types              # MIME type mappings
└── modules-enabled/        # Dynamic module configs (Debian)

/var/log/nginx/
├── access.log              # All requests
└── error.log               # Errors — check this first

/var/www/html/              # Default document root (Ubuntu)
/usr/share/nginx/html/      # Default document root (RHEL)

/run/nginx.pid              # Master process PID

---

Quick Start

# Install (Ubuntu/Debian)
sudo apt update && sudo apt install -y nginx

# Install (AlmaLinux/Rocky)
sudo dnf install -y nginx

# Start and enable
sudo systemctl enable --now nginx

# Verify
curl -I http://localhost
sudo nginx -t          # test config syntax
sudo nginx -v          # show version

---

Success Criteria

By the end of this documentation, you will be able to:

• Install and operate Nginx on any modern Linux distribution
• Write clean server blocks and location rules from scratch
• Configure PHP-FPM and connect it to Nginx via UNIX socket
• Build a reverse proxy for Node.js, Python, or any HTTP backend
• Tune compression, caching, HTTP/2, and worker settings
• Harden TLS, headers, and access controls
• Set up Cloudflare Full (Strict) SSL with Nginx origin
• Diagnose and fix 403, 404, 500, and upstream errors from the CLI
• Automate common tasks with bash scripts and cron
• Use opencode for AI-assisted config generation and log analysis