nginx

nginx Best Practices

NGINX is our go-to for web serving, reverse proxying, and load balancing. This guide outlines the mandatory best practices for NGINX configurations, ensuring readability, security, and optimal performance across all our deployments.

Critical Guidelines:

1. Code Organization and Structure

Always break down your NGINX configuration into small, focused, and reusable include files. This significantly improves maintainability and reduces cognitive load.

✅ GOOD: Modular Configuration

# /etc/nginx/nginx.conf
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;

    # Global HTTP settings
    include /etc/nginx/conf.d/http_common.conf;
    # Upstream server definitions
    include /etc/nginx/conf.d/upstreams/*.conf;
    # SSL/TLS profiles
    include /etc/nginx/conf.d/ssl_profiles/*.conf;
    # Virtual hosts
    include /etc/nginx/sites-enabled/*.conf;
}

❌ BAD: Monolithic Configuration

# /etc/nginx/nginx.conf (too long, hard to navigate)
# ... all server blocks, upstream definitions, SSL settings in one file ...
server {
    listen 80;
    server_name example.com;
    # ... hundreds of lines ...
}
upstream backend_app {
    # ... more lines ...
}
# ... SSL config ...

2. Consistent Formatting and Comments

Use two-space indentation. Add descriptive comments for every directive or block that isn't immediately obvious.

✅ GOOD

# /etc/nginx/sites-enabled/api.conf
server {
  listen 80;
  listen 443 ssl http2; # Enforce HTTPS and HTTP/2
  server_name api.example.com;

  # Include standard SSL settings
  include /etc/nginx/conf.d/ssl_profiles/default_ssl.conf;

  location / {
    proxy_pass http://api_backend; # Proxy to the API upstream
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
  }
}