Include directive for modular config in Nginx - Deep Dive

Overview - Include directive for modular config

What is it?

The include directive in nginx allows you to split your main configuration file into smaller, separate files. This helps organize settings by grouping related configurations together. Instead of one large file, you can manage multiple smaller files that nginx reads as if they were part of the main config.

Why it matters

Without the include directive, nginx configurations become large and hard to manage, especially for complex websites or multiple services. This can lead to mistakes and slow troubleshooting. Using include makes it easier to update parts of the config without touching the whole file, improving reliability and teamwork.

Where it fits

Before learning about the include directive, you should understand basic nginx configuration syntax and how nginx processes its config files. After mastering include, you can explore advanced nginx features like conditional includes, dynamic configuration reloads, and modular setups for multi-site hosting.

Mental Model

Core Idea

The include directive lets nginx treat multiple small config files as one big file, making configuration modular and easier to manage.

Think of it like...

Think of the include directive like a recipe book with chapters. Instead of one huge recipe list, each chapter covers a category like desserts or soups. When you want to cook, you open the whole book, but each chapter is separate and easy to update.

Main nginx config file
┌─────────────────────────────┐
│ http {                     │
│   include conf.d/*.conf;   │
│ }                          │
└─────────────┬───────────────┘
              │
  ┌───────────┴───────────┐
  │                       │
conf.d/site1.conf    conf.d/site2.conf
  │                       │
  └───────────┬───────────┘
              │
   Smaller config files included as part of main config

Build-Up - 6 Steps

1

Foundation

Basic nginx config structure

Concept: Understand how nginx reads a single configuration file.

Nginx uses a main configuration file, usually at /etc/nginx/nginx.conf. This file contains blocks like 'http', 'server', and 'location' that define how nginx behaves. All settings are written in this one file by default.

Result

You know where nginx looks for its main config and how it organizes settings inside it.

Understanding the single-file config is essential before breaking it into parts with include.

2

Foundation

What the include directive does

Concept: Learn that include tells nginx to read other files as part of the config.

The include directive is written as 'include path/to/file;' inside the nginx config. When nginx starts, it reads the main config and replaces the include line with the contents of the specified file(s). You can include one file or use wildcards like '*.conf' to include many files.

Result

Nginx treats included files as if their content was written directly in the main config.

Knowing that include merges files helps you organize configs without changing nginx's behavior.

3

Intermediate

Using wildcards for multiple files

🤔Before reading on: do you think nginx can include multiple files using wildcards like '*.conf'? Commit to yes or no.

Concept: Discover how to include many config files at once using wildcards.

You can write 'include conf.d/*.conf;' to include all files ending with .conf in the conf.d directory. This is useful to separate configs by site or feature. Nginx reads all matching files in alphabetical order.

Result

All matching files are loaded as part of the main config, allowing modular setups.

Using wildcards lets you add or remove config files without editing the main config, making management flexible.

4

Intermediate

Organizing configs by purpose

🤔Before reading on: do you think splitting configs by site or feature improves teamwork? Commit to yes or no.

Concept: Learn to group config files logically for easier maintenance.

Create folders like conf.d/sites/ and conf.d/features/. Put site-specific configs in sites/ and shared features like caching in features/. Include them separately or together in nginx.conf. This separation helps teams work on different parts without conflicts.

Result

Config files are easier to find, update, and review by purpose or team responsibility.

Logical organization reduces errors and speeds up troubleshooting in complex setups.

5

Advanced

Reloading nginx with included configs

🤔Before reading on: does nginx require a full restart to apply changes in included files? Commit to yes or no.

Concept: Understand how nginx reloads configs safely after changes in included files.

After editing any included config file, run 'nginx -t' to test syntax. Then reload nginx with 'nginx -s reload' or 'systemctl reload nginx'. Nginx reads all included files again without dropping connections, applying changes smoothly.

Result

Config changes take effect without downtime, even when using many included files.

Knowing reload behavior prevents downtime and encourages modular config updates.

6

Expert

Conditional includes and dynamic configs

🤔Before reading on: can nginx include files conditionally based on environment or variables? Commit to yes or no.

Concept: Explore advanced patterns like conditional includes and dynamic config generation.

Nginx does not support conditional includes directly. However, you can generate config files dynamically using scripts or tools before reload. For example, a deployment script can create or remove included files based on environment. This allows flexible, environment-specific setups.

Result

You can manage complex deployments by controlling which configs nginx includes indirectly.

Understanding nginx's static include nature leads to creative automation solutions for dynamic needs.

Under the Hood

When nginx starts or reloads, it reads the main config file line by line. Upon encountering an include directive, it pauses reading the main file and reads the specified included file(s) content. It then inserts that content into the configuration as if it was written inline. This process is recursive, so included files can themselves include others. After reading all files, nginx parses the combined configuration into internal data structures to control its behavior.

Why designed this way?

The include directive was designed to keep nginx configuration flexible and maintainable. Early web servers had monolithic configs that became hard to manage. Splitting configs into modular files allows teams to work independently and reuse common settings. The design avoids runtime complexity by resolving includes at startup or reload, ensuring fast and predictable behavior.

┌───────────────┐
│ nginx.conf    │
│               │
│ include conf.d/*.conf; ──────┐
└───────────────┘              │
                              ▼
                  ┌─────────────────────┐
                  │ conf.d/site1.conf   │
                  ├─────────────────────┤
                  │ conf.d/site2.conf   │
                  └─────────────────────┘
                              │
                              ▼
                  Combined config parsed by nginx

Myth Busters - 4 Common Misconceptions

Quick: Does nginx reload automatically when you change an included config file? Commit yes or no.

Common Belief: Nginx automatically detects changes in included files and reloads itself.

Reality: Nginx does not watch files for changes. You must manually reload nginx after editing any config file, included or not.

Why it matters: Assuming automatic reload leads to config changes not applying, causing confusion and downtime.

Quick: Can you include files with relative paths outside the main config directory? Commit yes or no.

Common Belief: You can include any file anywhere on the system using relative paths.

Reality: Include paths are relative to the main config file or absolute. Using relative paths outside allowed directories can cause errors or security risks.

Why it matters: Incorrect paths cause nginx startup failures or security vulnerabilities.

Quick: Does the order of included files matter? Commit yes or no.

Common Belief: The order of included files does not affect nginx behavior.

Reality: Nginx reads included files in alphabetical order, so order can affect which settings take precedence.

Why it matters: Ignoring order can cause unexpected overrides and bugs.

Quick: Can included files contain directives outside allowed contexts? Commit yes or no.

Common Belief: You can put any directive in any included file regardless of context.

Reality: Included files must contain directives valid for the context where they are included, or nginx will fail to start.

Why it matters: Misplaced directives cause nginx to fail silently or refuse to start.

Expert Zone

1

Included files can themselves include other files, allowing deep modular hierarchies, but this can complicate debugging if overused.

2

Using include with wildcards loads files alphabetically, so naming files with prefixes (like 01-, 02-) controls load order precisely.

3

Nginx does not support conditional includes natively, so dynamic configuration requires external tooling or scripting before reload.

When NOT to use

Avoid using include for very small or single-use configurations where it adds unnecessary complexity. For dynamic runtime changes, consider using nginx's variables or external API-driven configuration tools instead of static includes.

Production Patterns

In production, teams often separate site configs into conf.d/sites/ and shared features into conf.d/features/. Deployment pipelines generate or update included files per environment. Reloads are automated after config validation to ensure zero downtime. Naming conventions enforce load order and prevent conflicts.

Connections

Modular programming

The include directive applies the modular programming principle to configuration files.

Understanding modular programming helps grasp why splitting configs improves maintainability and reduces errors.

Makefile includes

Similar to how Makefiles include other files to organize build rules, nginx includes config files to organize server rules.

Knowing Makefile includes clarifies how include directives help manage complexity by breaking large files into smaller parts.

Book chapters in publishing

Like chapters in a book that combine to form a complete story, included config files combine to form the full nginx configuration.

Seeing config files as chapters helps appreciate the clarity and flexibility gained by modular design.

Common Pitfalls

#1 Editing included config files but forgetting to reload nginx.

Wrong approach:

vim /etc/nginx/conf.d/site.conf
# make changes
# no reload command run

Correct approach:

vim /etc/nginx/conf.d/site.conf
# make changes
nginx -t
systemctl reload nginx

Root cause:

Misunderstanding that nginx does not auto-reload configs after changes.

#2 Including files with incorrect relative paths causing nginx startup failure.

Wrong approach:

include ../otherdir/mysite.conf;

Correct approach:

include /etc/nginx/otherdir/mysite.conf;

Root cause:

Confusing relative paths with respect to main config file location.

#3 Placing server block directives inside an included file meant for http context.

Wrong approach:

In conf.d/common.conf:
server {
listen 80;
}

Correct approach:

In conf.d/common.conf:
# only http-level directives here
proxy_cache_path /cache keys_zone=mycache:10m;

Root cause:

Not matching included file content to the context where it is included.

Key Takeaways

The include directive in nginx lets you split your configuration into smaller, manageable files that nginx reads as one combined config.

Using include improves organization, teamwork, and reduces errors by separating concerns into logical files or folders.

Nginx reads included files at startup or reload, so you must reload nginx manually after changes to apply them.

Included files must have valid directives for the context they are included in, and their load order can affect configuration behavior.

Advanced use involves scripting or automation to generate included files dynamically, since nginx does not support conditional includes natively.