The Nginx Configuration File Structure
Nginx configuration is organized as a tree of nested contexts, written with curly braces, inside which individual directives are set, each terminated by a semicolon. The outermost scope is the main context, which contains the events block and the http block; the http block contains one or more server blocks (virtual hosts); and each server block contains one or more location blocks that match specific URI patterns. Forgetting a semicolon or mismatching a brace is the single most common cause of a failed 'nginx -t'.
Cricket analogy: The nesting of http inside main, and server inside http, is like a series (main) containing individual matches (http), each match containing innings (server), and each innings containing overs (location), each level inheriting rules from the one above.
Contexts: main, events, http, server, location
Directives set at a broader context are automatically inherited by every narrower context nested inside it, unless a narrower context explicitly redefines the same directive. For example, setting 'gzip on;' at the http level enables compression for every server block by default, but a specific server block can override it with 'gzip off;' just for that virtual host, and a location block can override it again just for one URI pattern.
Cricket analogy: An ICC playing condition set at the tournament level (http) applies to every match (server) automatically, like the DRS review count, unless a specific match's local regulations (location) explicitly changes it.
# /etc/nginx/nginx.conf (main context)
user www-data;
worker_processes auto;
events {
worker_connections 1024;
}
http {
gzip on;
include mime.types;
include /etc/nginx/conf.d/*.conf;
server {
listen 80;
server_name blog.example.com;
location / {
root /var/www/blog;
}
location /admin/ {
gzip off; # overrides the http-level default just for this location
proxy_pass http://127.0.0.1:8080/;
}
}
}Include Directives and Modularity
Rather than writing every server block into a single monolithic nginx.conf, production setups typically use 'include /etc/nginx/conf.d/*.conf;' or the Debian-style sites-available/sites-enabled pattern, where each site's server block lives in its own file and a symlink in sites-enabled activates it. This keeps configuration modular: adding, disabling, or removing a site is a matter of adding or removing one file or symlink, without touching the shared main configuration.
Cricket analogy: Splitting configuration into included files, like sites-enabled per domain, is like a cricket board maintaining separate rulebooks per format, Test, ODI, T20, each included into the master handbook.
Directive inheritance in Nginx is not additive for most directives: when a narrower context sets a directive that was also set in a parent context, the child's value fully replaces the parent's for that context, it does not merge with it. Array-like directives such as 'add_header' are a notable exception where redefining them in a child context can hide inherited values from the parent, so many teams re-declare all needed add_header lines explicitly at each level.
- Nginx configuration is a nested tree of contexts: main, events, http, server, and location.
- Directives use a semicolon terminator; contexts use curly braces.
- Narrower contexts inherit directives from broader ones unless they explicitly override them.
- gzip, proxy settings, and many other directives can be set at http level and overridden per server or location.
- 'include' directives (e.g. conf.d/*.conf or sites-enabled) split configuration into modular per-site files.
- Most directive inheritance replaces rather than merges with the parent value.
- add_header and similar array-like directives can silently hide parent values when redefined in a child context.
Practice what you learned
1. Which context directly contains server blocks in a standard Nginx configuration?
2. What happens when a directive is set at the http level and then redefined inside a specific location block?
3. What is the purpose of 'include /etc/nginx/conf.d/*.conf;' in the main config?
4. What terminates a single directive in Nginx configuration syntax?
5. Which directive type is called out as an exception where redefining it in a child context can hide parent values instead of merging?
Was this page helpful?
You May Also Like
Nginx Architecture and Worker Processes
How Nginx's master-worker process model and event-driven design deliver high concurrency with a small memory footprint.
Installing and Running Nginx
How to install Nginx via package managers or Docker, and how to manage the running service safely.
Serving Static Content
How Nginx efficiently serves static files using root, alias, sendfile, caching headers, and try_files.
Related Reading
Related Study Notes in DevOps
Browse all study notesAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics