> For the complete documentation index, see [llms.txt](https://wisdom.gitbook.io/gyan/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wisdom.gitbook.io/gyan/nginx/core-concepts-and-basics.md).

# Core Concepts and Basics

### The Event-Driven Architecture of NGINX

One of the defining characteristics of NGINX is its **event-driven, asynchronous architecture**. Unlike traditional web servers that use a process-per-connection or thread-per-connection model (like Apache), NGINX follows an event-driven approach where a single process can handle thousands of simultaneous connections with minimal resource consumption.

#### **How It Works:**

1. **Master Process:** Manages worker processes, reads configuration files, and maintains overall control.
2. **Worker Processes:** Handle actual request processing. Each worker operates independently, sharing no state with others.
3. **Event Loop:** Instead of blocking threads, NGINX uses an event loop where requests are processed asynchronously, improving scalability.
4. **Non-Blocking I/O:** NGINX uses efficient OS-level mechanisms (like epoll in Linux) to handle multiple connections within a single thread.

### The NGINX Configuration Structure

NGINX configurations are defined in a structured format, primarily located in `/etc/nginx/nginx.conf` (on Linux) or in separate configuration files included from `conf.d/`.

#### **Core Configuration Blocks:**

* **Main Context:** Global settings that affect the entire NGINX server (worker processes, logging, event handling).
* **Events Context:** Defines how NGINX should handle connections (worker connections, multi-accept behaviour, etc.).
* **HTTP Context:** The most important section, where web server settings, reverse proxying, and caching rules are defined.
* **Server Block:** Defines a virtual host that listens on a specific port.
* **Location Block:** Defines how NGINX should process specific request URIs.
* **Upstream Block:** Defines backend servers for load balancing.
* **Include Directives:** Allows modular configuration by including separate files.

#### **Example NGINX Configuration:**

```nginx
worker_processes auto;
events {
    worker_connections 1024;
}
http {
    include mime.types;
    server {
        listen 80;
        server_name example.com;
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}
```

### **Core Configuration Files:**

1. **`/etc/nginx/nginx.conf`** – The main configuration file that defines global settings such as worker processes, logging, and event handling.
2. **`/etc/nginx/mime.types`** – Contains a list of MIME types to properly serve different file formats.
3. **`/etc/nginx/conf.d/*.conf`** – Stores additional modular configuration files, commonly used for organizing virtual hosts and specific settings.
4. **`/etc/nginx/sites-available/`** – Directory where virtual host configuration files are stored but not necessarily active.
5. **`/etc/nginx/sites-enabled/`** – Contains symlinked files from `sites-available/`, enabling the configured virtual hosts.

#### **Logging and SSL Files:**

6. **`/var/log/nginx/access.log`** – Logs every request received by NGINX, useful for monitoring and debugging.
7. **`/var/log/nginx/error.log`** – Captures error messages and debugging information.
8. **`/etc/nginx/ssl/`** – Directory where SSL/TLS certificates and keys are stored for securing HTTPS connections.

#### **Additional Important Files:**

9. **`/etc/nginx/modules/`** – Contains dynamically loaded modules that extend NGINX functionality.
10. **`/usr/share/nginx/html/`** – Default root directory for serving static content when no custom configuration is specified.

### Request Handling Lifecycle in NGINX

Understanding how NGINX processes a request helps in debugging and optimizing performance.

#### **Step-by-Step Flow:**

1. **Client Sends Request** → NGINX receives the request from a browser or API client.
2. **NGINX Matches Server Block** → Determines which `server {}` block should handle the request based on `server_name` and `listen` directives.
3. **Location Matching** → The request is checked against defined `location` blocks to determine how it should be processed.
4. **Content Handling:**
   * If the requested file exists (static file), it is served immediately.
   * If proxying is required, the request is forwarded to an upstream server (e.g., a backend application).
   * If caching is enabled, NGINX checks if a cached response is available.
5. **Response Sent to Client** → NGINX returns the requested data, applying any configured compression, caching, or security rules.

### Static vs. Dynamic Content Handling

#### **Static Content (HTML, CSS, JS, Images, etc.)**

* NGINX is optimized to serve static files directly from the filesystem.
* Uses efficient system calls (`sendfile`, `tcp_nopush`) for high-speed delivery.

#### **Dynamic Content (PHP, Node.js, Python, etc.)**

* NGINX does not process dynamic content natively but can **proxy** requests to application servers (e.g., PHP-FPM, Node.js, Gunicorn for Python).
* Acts as a reverse proxy, handling SSL termination and load balancing before passing the request to the backend.

### Directives in NGINX

NGINX is configured using **directives**, which define behaviours within specific contexts.

#### **Common Directives:**

* `worker_processes` – Number of worker processes to handle requests.
* `worker_connections` – Number of simultaneous connections each worker can handle.
* `listen` – Defines the IP and port the server listens on.
* `server_name` – Specifies the hostname for a virtual server.
* `root` – Defines the root directory for static files.
* `index` – Specifies default files to serve.
* `proxy_pass` – Forwards requests to backend servers.
* `location` – Defines how specific URL patterns should be handled.
* `gzip` – Enables compression for faster content delivery.

### NGINX Modules and Their Role

NGINX’s functionality can be extended using **modules**. Some modules are built-in, while others must be compiled separately.

#### **Important Modules:**

* **Core Modules:** Provide basic web server functionality.
* **HTTP Modules:** Handle caching, compression, authentication, and proxying.
* **Stream Modules:** Support TCP and UDP proxying.
* **Mail Modules:** Enable email proxying.
* **Third-Party Modules:** Extend functionality (e.g., Lua scripting, security enhancements, custom logging).

#### **Enabling Modules:**

* Some modules are enabled by default.
* Others require compilation (`--with-module-name` during build time).
* Dynamic modules can be loaded using `load_module` in the configuration.

### Key Performance Optimizations in NGINX

#### **Worker Processes and Connections**

* `worker_processes auto;` → Automatically sets the number of worker processes based on CPU cores.
* `worker_connections 1024;` → Defines how many clients each worker can handle simultaneously.
* `multi_accept on;` → Allows a worker to accept multiple new connections at once, reducing latency.

#### **Keepalive & Connection Handling**

* `keepalive_timeout 65;` → Reduces overhead of opening new connections.
* `sendfile on;` → Optimizes file serving by sending data directly from disk to the network.
* `gzip on;` → Enables compression for faster page loads.

#### **Reverse Proxy & Load Balancing**

* `proxy_pass http://backend;` → Routes requests to backend servers.
* `upstream backend { server app1:3000; server app2:3000; }` → Distributes traffic across multiple application instances.
* `proxy_cache_path` → Stores frequently accessed responses to reduce backend load.

### Conclusion

Understanding the **core concepts of NGINX** is fundamental for using it effectively in production environments. Its event-driven architecture, efficient request handling, modular configuration, and extensive module support make it a versatile tool for high-performance web serving, reverse proxying, and load balancing. Mastering these basics will provide a solid foundation before diving into advanced topics like security hardening, caching strategies, and API gateway setups.

In the next post, we'll explore **Reverse Proxy and Load Balancing in NGINX** with real-world use cases!