Separate config files per site in Nginx - Deep Dive

Overview - Separate config files per site

What is it?

Separate config files per site means organizing each website's settings in its own file instead of putting all sites in one big file. This makes managing multiple websites easier and safer. Each file contains rules about how to handle requests for that specific site. Nginx reads these files to know how to serve each website correctly.

Why it matters

Without separate config files, all website settings mix together, making it hard to find and fix problems. If one site has an error, it can affect others. Separate files let you update or add sites without risking the whole server. This approach saves time and reduces mistakes, especially when hosting many websites.

Where it fits

Before learning this, you should understand basic nginx configuration and how nginx serves websites. After this, you can learn about advanced nginx features like load balancing, SSL setup per site, and automation tools that manage configs.

Mental Model

Core Idea

Organizing each website's settings into its own file keeps configurations clear, safe, and easy to manage.

Think of it like...

It's like having a separate folder for each project on your desk instead of mixing all papers in one pile. When you want to work on one project, you open its folder without disturbing others.

nginx.conf
├── sites-available
│   ├── site1.conf
│   ├── site2.conf
│   └── site3.conf
└── sites-enabled
    ├── site1.conf -> ../sites-available/site1.conf
    └── site2.conf -> ../sites-available/site2.conf

Build-Up - 7 Steps

1

Foundation

Basic nginx config structure

Concept: Learn how nginx uses a main config file and includes other files.

Nginx has a main config file usually at /etc/nginx/nginx.conf. This file can include other files or folders using the 'include' directive. For example, it can include all files in /etc/nginx/sites-enabled/*.conf to load site-specific configs.

Result

Nginx reads the main config and then loads all included site config files to know how to serve each site.

Understanding the include directive is key to splitting configs safely and cleanly.

2

Foundation

What is a server block in nginx

Concept: A server block defines settings for one website or domain.

A server block starts with 'server { ... }' and contains settings like the domain name, root folder, and ports. Each site you host needs its own server block to tell nginx how to handle requests for that site.

Result

Nginx uses server blocks to decide which site to serve based on the request's domain or IP.

Knowing server blocks lets you separate sites logically in config files.

3

Intermediate

Creating separate config files per site

🤔Before reading on: do you think you can put multiple server blocks in one file or should each site have its own file? Commit to your answer.

Concept: Each site gets its own config file with one server block inside.

Create a file like /etc/nginx/sites-available/site1.conf with a server block for site1. Repeat for other sites. This keeps each site's settings isolated and easy to edit.

Result

You have multiple small config files, each controlling one site.

Separating configs reduces risk of accidental changes affecting other sites.

4

Intermediate

Using sites-available and sites-enabled folders

🤔Before reading on: do you think nginx reads all files in sites-available or only those linked in sites-enabled? Commit to your answer.

Concept: sites-available holds all site configs; sites-enabled holds links to active sites.

Put all site config files in sites-available. Then create symbolic links in sites-enabled to activate sites. Nginx only loads configs from sites-enabled. This lets you disable a site by removing its link without deleting the config.

Result

You can easily enable or disable sites by adding or removing links.

This system provides safe control over which sites nginx serves.

5

Intermediate

Reloading nginx after config changes

Concept: Nginx must reload configs to apply changes without downtime.

After adding or changing site config files, run 'sudo nginx -t' to test syntax. If OK, run 'sudo systemctl reload nginx' to apply changes without stopping the server.

Result

Nginx applies new site configs smoothly without interrupting users.

Testing configs before reload prevents server crashes from bad syntax.

6

Advanced

Managing multiple sites with automation

🤔Before reading on: do you think manual symlink creation scales well for many sites? Commit to your answer.

Concept: Automate config file creation and enabling for many sites using scripts or tools.

Use scripts or configuration management tools like Ansible to create site config files and symlinks automatically. This reduces human error and speeds up deploying many sites.

Result

You can manage dozens or hundreds of sites reliably and quickly.

Automation is essential for scaling site management beyond a few sites.

7

Expert

Avoiding config conflicts and overlaps

🤔Before reading on: do you think two server blocks can share the same domain and port without issues? Commit to your answer.

Concept: Nginx cannot serve two server blocks with the same domain and port; conflicts cause errors or unexpected behavior.

Ensure each site config uses unique server_name and port combinations. Use default_server only once per port. Conflicts cause nginx to pick one server block unpredictably or fail to start.

Result

Proper unique configs prevent downtime and routing errors.

Knowing how nginx matches requests to server blocks prevents hard-to-debug production issues.

Under the Hood

Nginx reads the main config file first, then processes all included files in order. Each server block registers a listener for specific domains and ports. When a request arrives, nginx matches the Host header and port to the correct server block. Symbolic links in sites-enabled point to actual config files in sites-available, allowing dynamic enabling or disabling without moving files.

Why designed this way?

Separating configs into sites-available and sites-enabled was designed to simplify managing many sites on one server. It allows admins to keep all configs but only activate some, reducing risk and improving organization. This pattern was adopted from Debian-based Linux distributions and became a best practice for nginx.

┌─────────────────────┐
│ /etc/nginx/nginx.conf│
│  includes sites-enabled/*.conf
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ /etc/nginx/sites-enabled/
│  ├─ site1.conf -> ../sites-available/site1.conf
│  └─ site2.conf -> ../sites-available/site2.conf
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ /etc/nginx/sites-available/
│  ├─ site1.conf (server block for site1)
│  └─ site2.conf (server block for site2)
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does nginx automatically reload configs when you change a file? Commit yes or no.

Common Belief: Nginx automatically detects and applies config changes immediately.

Reality: Nginx requires a manual reload command to apply config changes; it does not watch files.

Why it matters: Without reloading, changes won't take effect, causing confusion and wasted troubleshooting.

Quick: Can two server blocks listen on the same port and domain without conflict? Commit yes or no.

Common Belief: You can have multiple server blocks with the same domain and port safely.

Reality: Nginx picks one server block unpredictably or fails to start if there are conflicts.

Why it matters: Conflicts cause downtime or wrong site responses, hard to debug in production.

Quick: Does removing a config file from sites-available disable the site immediately? Commit yes or no.

Common Belief: Deleting a config file from sites-available disables the site instantly.

Reality: Nginx only loads configs from sites-enabled; removing from sites-available alone does nothing if symlink remains.

Why it matters: Misunderstanding this can cause sites to stay active unexpectedly.

Quick: Is it safe to put all site configs in one file instead of separate files? Commit yes or no.

Common Belief: One big config file for all sites is just as good as separate files.

Reality: One big file is harder to manage, increases risk of errors, and slows down troubleshooting.

Why it matters: Poor organization leads to mistakes and longer downtime when fixing issues.

Expert Zone

1

Symbolic links in sites-enabled can point anywhere, allowing flexible config storage beyond default folders.

2

Using include with wildcards loads files in alphabetical order, which can affect config override behavior.

3

Nginx caches config state; some changes require full restart, not just reload, especially with module changes.

When NOT to use

For very simple single-site servers, separate config files add unnecessary complexity. Instead, use a single config file. Also, for dynamic environments like containers, config management tools or environment variables might be better than static files.

Production Patterns

In production, teams use automation tools to generate site configs from templates, store them in version control, and deploy with CI/CD pipelines. They use sites-available/sites-enabled for safe rollbacks and staged rollouts. Monitoring tools check config syntax and server health after reloads.

Connections

Version Control Systems

Builds-on

Managing separate config files per site works best when combined with version control to track changes and collaborate safely.

Containerization (Docker)

Alternative approach

Containers often package site configs inside images, reducing the need for separate config files on the host, showing a different way to manage site configs.

Library Organization in Software Development

Same pattern

Just like separating code into modules or libraries for clarity and reuse, separating site configs improves clarity and reduces errors.

Common Pitfalls

#1 Editing site config but forgetting to reload nginx

Wrong approach:

sudo nano /etc/nginx/sites-available/site1.conf
# make changes
# no reload command run

Correct approach:

sudo nano /etc/nginx/sites-available/site1.conf
# make changes
sudo nginx -t
sudo systemctl reload nginx

Root cause:

Not knowing nginx requires a reload to apply config changes.

#2 Creating duplicate server blocks for the same domain and port

Wrong approach:

server {
listen 80;
server_name example.com;
...
}

server {
listen 80;
server_name example.com;
...
}

Correct approach:

server {
listen 80;
server_name example.com;
...
}

Root cause:

Misunderstanding how nginx matches requests to server blocks.

#3 Removing config file from sites-available but leaving symlink in sites-enabled

Wrong approach:

rm /etc/nginx/sites-available/site2.conf
# symlink still exists in sites-enabled

Correct approach:

rm /etc/nginx/sites-enabled/site2.conf
rm /etc/nginx/sites-available/site2.conf

Root cause:

Confusing sites-available and sites-enabled roles.

Key Takeaways

Separate config files per site keep nginx configurations organized and reduce risk of errors.

Using sites-available and sites-enabled folders allows safe enabling and disabling of sites without deleting configs.

Always test nginx config syntax and reload nginx after changes to apply them safely.

Avoid duplicate server blocks for the same domain and port to prevent conflicts and downtime.

Automation and version control improve managing many site configs in production environments.