Learning nginx - Case Study: Complete Production-Grade NGINX Gateway Architecture

#Introduction

This is the peak of your journey. Episode 20 weaves together all the material from the previous 19 episodes into one complete case study: designing an NGINX production gateway for an enterprise web application. Not an ideal configuration on paper, but a real architecture used in production. You'll assemble a single HTTPS entry point, the security perimeter, JSON observability, a performance layer, upstream routing with a maintenance fallback, and a production readiness checklist to audit your own server.

#Architecture Overview

#The Traffic Flow from Client to Backend

Our gateway architecture has five layers running in sequence: a single HTTPS entry point with auto-renewing Let's Encrypt certificates and HTTP/2, a security perimeter with HSTS and security headers, observability with JSON access logs for Grafana Loki, a performance layer with microcaching and compression, and upstream routing to three backend containers with a maintenance page fallback. All layers are assembled in one modular nginx.conf, and we'll build it up one by one.

#Single Entry Point and Security Perimeter

#HTTPS Entry Point with HTTP/2

The main server block uses HTTPS, HTTP/2, and an HTTP redirect:

server {
    listen 80;
    server_name app.example.com;
    return 301 https://$host$request_uri;
}
 
server {
    listen 443 ssl http2;
    server_name app.example.com;
 
    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
 
    include /etc/nginx/includes/ssl.conf;
    include /etc/nginx/includes/security-headers.conf;
}

#Rate Limiting and Body Limits

http {
    limit_req_zone $binary_remote_addr zone=gateway_zone:10m rate=10r/s;
    limit_conn_zone $binary_remote_addr zone=gateway_conn:10m;
 
    server {
        limit_req zone=gateway_zone burst=30 nodelay;
        limit_conn gateway_conn 20;
        client_max_body_size 10M;
    }
}

#Observability and Performance Layer

#JSON Access Logs for Grafana Loki

Observability starts with logs. We'll use the JSON format from episode 15:

http {
    log_format json_gateway escape=json
        '{'
            '"time":"$time_iso8601",'
            '"remote_addr":"$remote_addr",'
            '"request":"$request",'
            '"status":$status,'
            '"request_time":$request_time,'
            '"upstream_response_time":"$upstream_response_time",'
            '"http_user_agent":"$http_user_agent"'
        '}';
 
    access_log /var/log/nginx/access.log json_gateway;
}

#Performance: Microcaching, Open File Cache, Gzip

http {
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=gateway_cache:50m
                     max_size=2g inactive=60m;
 
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;
    gzip_vary on;
 
    open_file_cache max=10000 inactive=20s;
 
    server {
        location / {
            proxy_cache gateway_cache;
            proxy_cache_valid 200 302 1m;
            proxy_cache_lock on;
            proxy_cache_use_stale updating error timeout;
        }
    }
}

The 1-minute microcaching with proxy_cache_use_stale keeps the gateway responsive even while the backend is slow or being updated.

#Upstream Routing with Fallback

#Three Backends and a Maintenance Page

The last part is the backend cluster and the fallback. When all backends are down, the application must still show a polite page, not an empty error:

http {
    upstream backend_app {
        least_conn;
        server 10.0.1.11:3000 max_fails=3 fail_timeout=30s;
        server 10.0.1.12:3000 max_fails=3 fail_timeout=30s;
        server 10.0.1.13:3000 max_fails=3 fail_timeout=30s backup;
    }
 
    server {
        listen 443 ssl http2;
        server_name app.example.com;
 
        location / {
            proxy_pass http://backend_app;
            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_set_header X-Forwarded-Proto $scheme;
 
            proxy_connect_timeout 10s;
            proxy_read_timeout 60s;
 
            proxy_cache gateway_cache;
            proxy_cache_valid 200 302 1m;
        }
 
        location = /maintenance.html {
            internal;
            root /var/www/gateway;
        }
 
        error_page 502 503 504 /maintenance.html;
    }
}

error_page 502 503 504 /maintenance.html; redirects all upstream errors to the maintenance page. The two primary backends use least_conn; the third server is of type backup so it's only used when both are down. When all backends fail, users still see a clean maintenance page instead of a raw error screen.

#Production Readiness Checklist

#NGINX Server Security Audit

• nginx -t is clean and the configuration is in version control.
• All HTTP traffic is redirected to HTTPS with status 301.
• HSTS, security headers, and server_tokens off are active.
• Let's Encrypt auto-renewal runs and is verified with a dry-run.
• JSON access logs are sent to Loki; the error log is monitored with alerting.
• The maintenance fallback is tested by shutting down all backends.
• File and folder permissions are correct for the www-data user.

Test the fallback right now: shut down all backends and see if the maintenance page appears. This is the moment to prove your architecture is production-ready.

#Conclusion

Episode 20 closed the Learning nginx journey with a complete work: you designed a production gateway with a single HTTPS entry point, the security perimeter, JSON observability, a performance layer, and upstream routing with a maintenance fallback.

Key takeaways:

• The gateway architecture consists of entry, security, observability, performance, and routing layers.
• All layers are assembled from the reusable snippets you learned.
• JSON logging makes the gateway integrate with Grafana Loki and observability pipelines.
• Microcaching maintains throughput when traffic rises and the backend is slow.
• error_page 502 503 504 plus a backup backend makes the maintenance fallback automatic.
• The production readiness checklist is the final audit before go-live.

The Learning nginx series has come to an end. You now master NGINX from pre-requisites all the way to production-grade architecture: configuration, virtual hosts, reverse proxying, load balancing, caching, SSL/TLS, security, authentication, realtime protocols, modularity, logging, performance, the stream module, and troubleshooting. Apply this material, test it on your server, and make NGINX part of your production engineering skill set. Happy building!