When working with nginx configuration files, we often need to include other conf files. While absolute paths work, they make configurations less portable between environments. Consider this common scenario:

server {
  listen       80;
  server_name  localhost;
  include "/etc/nginx/conf.d/apis/basic.conf";
}

The absolute path becomes problematic when you need to move configurations between development, staging, and production environments.

Nginx does support relative paths in include directives, but there's an important detail to understand:

include "../apis/basic.conf";  # Relative to nginx prefix path by default
include "conf.d/apis/basic.conf";  # Also relative to prefix

The key is knowing that relative paths are resolved against the --prefix path specified during nginx compilation (usually /etc/nginx or /usr/local/nginx).

For true relative-to-current-file includes, consider these approaches:

# Option 1: Using the 'root' directive
server {
  root /path/to/your/configs;
  include "apis/basic.conf";
}

# Option 2: Environment variables (requires nginx 1.19+)
env CONFIG_PATH=/path/to/configs;
include "${CONFIG_PATH}/apis/basic.conf";

# Option 3: Symlinks
ln -s /path/to/apis/basic.conf /etc/nginx/conf.d/apis/basic.conf

For maximum portability:

• Use relative paths from nginx's prefix
• Document your directory structure
• Consider using Docker or containerization to standardize paths
• Implement configuration management tools (Ansible, Chef, etc.)

Here's how we structure our microservices configuration:

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

# /etc/nginx/conf.d/api_gateway.conf
include api_routes/*.conf;  # Relative to prefix

This approach maintains clean separation while allowing relative includes.

When working with Nginx configuration files, you'll often need to split configurations into modular files. The include directive is perfect for this, but many developers struggle with path resolution.

# Absolute path example (works but inflexible)
include /etc/nginx/conf.d/*.conf;

# What we want: relative path from current file
include "../sites/example.com.conf";

Nginx processes include paths relative to its main configuration directory (typically /etc/nginx), not the current file's location. This behavior often confuses developers expecting filesystem-relative paths.

Here are practical approaches to achieve modular configurations:

1. Environment Variable Workaround

env NGINX_CONF_PATH=/path/to/your/configs;
# In your nginx.conf
include "$NGINX_CONF_PATH/modules/*.conf";

2. Root-Relative Paths

Structure your configs under Nginx's root directory:

# Assuming nginx root is /etc/nginx
include "conf.d/sites/backend.conf";

3. Symbolic Links

For development environments:

ln -s /your/project/configs /etc/nginx/includes
# Then reference normally
include "includes/api_gateway.conf";

• Keep all configs under Nginx's primary directory
• Use clear, consistent naming conventions
• Document include dependencies
• Consider using wildcards for groups of configs

# Example structure
include "conf.d/common/*.conf";
include "conf.d/sites/*.conf";
include "conf.d/locations/*.conf";

Always verify includes work as expected:

nginx -t
# Check which files are actually loaded
nginx -T 2>&1 | grep -i "reading configuration"