Learning nginx - Anatomy of the Configuration File (nginx.conf) & Directives

#Introduction

All of NGINX's capabilities are determined by a single file: /etc/nginx/nginx.conf. This Episode 2 breaks down the anatomy of the NGINX configuration file — the context hierarchy, directive syntax rules, and how to modularize configuration. This is the foundation you'll use in every subsequent episode.

After this episode, you'll no longer see nginx.conf as a mysterious file. You'll understand where a directive must be placed, why server_name can't be written outside the http context, and how one giant file gets split into neat, small pieces.

#Context Hierarchy Structure in NGINX

#The main Context

The outermost context is called main. Directives at this level configure NGINX globally, such as the user that runs processes and the number of workers:

user www-data;
worker_processes auto;
error_log /var/log/nginx/error.log warn;

#The events Context

The events context configures how workers handle connections:

events {
    worker_connections 1024;
    use epoll;
}

#The http Context

The http context wraps all HTTP configuration: server blocks, locations, upstreams, and much more. Almost every directive we discuss in this series lives inside http.

#The server and location Contexts

Inside http, the server context defines a virtual host (one domain or one IP+port pair), and inside server, the location context handles specific URIs. Both will be covered in depth in episodes 3 and 4.

#Directive Syntax Rules

#Simple Directives

A simple directive is a single line, ending with a semicolon ;. Examples are worker_processes auto; and server_name example.com;. The semicolon is mandatory; if it's missing, nginx -t will reject the configuration.

#Block Directives

A block directive takes the form of a name followed by curly braces { } and contains other directives inside. The clearest examples are http, events, server, and location. The curly braces mark the scope boundary, so the directives inside only apply to that context.

worker_processes auto;
 
events {
    worker_connections 1024;
}
 
http {
    sendfile on;
}

Notice: sendfile on; is inside http, and worker_connections is inside events. If they were swapped, NGINX would reject the configuration because the directive isn't recognized in that context.

#Default Ubuntu Directories and Files

On Ubuntu, the main nginx.conf is quite thin because most configuration is included:

• /etc/nginx/conf.d/*.conf
• /etc/nginx/sites-enabled/*

Ubuntu also provides snippets/ for reusable configuration pieces, and mime.types for mapping file extensions to MIME types.

#Modularizing Configuration with include

#One Big File, Many Problems

Imagine all server blocks, upstreams, and caches written into a single nginx.conf. The file would be long, hard to read, and prone to conflicts when many teams edit it. The solution: the include directive.

The include directive inserts another file's contents as if it were written directly at that position:

http {
    include /etc/nginx/mime.types;
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

The *.conf and * patterns are wildcards. The practical rule: per-server specific configuration is written as a separate file in conf.d/ or sites-enabled/, then included automatically. Whenever there's a change, just run nginx -t and reload.

#A Realistic nginx.conf Example

Here's a combination of everything we've covered — a preview of the file we'll build up step by step throughout the series:

user www-data;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
 
events {
    worker_connections 1024;
}
 
http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    sendfile on;
    keepalive_timeout 65;
 
    include /etc/nginx/conf.d/*.conf;
 
    server {
        listen 80 default_server;
        server_name _;
        root /var/www/html;
        index index.html;
    }
}

Save it, then test with nginx -t. If the output says syntax is ok, you've successfully written a valid configuration on your first try.

#Conclusion

Episode 2 gave you the keys to reading and writing nginx.conf: the context hierarchy of main, events, http, server, and location; the rules for simple directives ending with semicolons and block directives wrapped in curly braces; and the modularization pattern with include.

Key takeaways:

• The main context holds global settings; events configures worker connections.
• The http context wraps server and location; server is a virtual host.
• Simple directives end with ;, block directives use { }.
• Directives are only valid in certain contexts — nginx -t will reject mistakes.
• Use include to split up large configurations.
• Always test with nginx -t before reloading.

In the next episode we'll set up a static web server and virtual hosts (server blocks) — defining several domains in one NGINX, configuring the listen and server_name directives, the difference between root and alias, index, and error_page. Have your domain or server IP ready, because from now on we're writing real configuration!