nginx: Add documentation to the configuration file (rust-lang#7327)

config/nginx.conf.erb

@@ -1,19 +1,29 @@
+# Disable "daemon" mode, which causes nginx to run in the foreground
 daemon off;
-#Heroku dynos have at least 4 cores.
+
+# Define the number of worker processes (Heroku dynos have at least 4 cores)
 worker_processes <%= ENV['NGINX_WORKERS'] || 4 %>;
 
 events {
+    # Explicitly force nginx to use the "epoll" connection processing method
+    # (see http://nginx.org/en/docs/events.html)
 	use epoll;
+
 	accept_mutex on;
+
+	# Set the maximum number of simultaneous connections that can be opened by a worker process
 	worker_connections 2048;
 }
 
 http {
-	set_real_ip_from 10.0.0.0/8;
-	set_real_ip_from 127.0.0.0/24;
+    # Use the `X-Forwarded-For` to replace the client address (`$remote_addr`).
 	real_ip_header X-Forwarded-For;
+	# Ignore "trusted addresses" (see `set_real_ip_from` below) when determining the real user IP
 	real_ip_recursive on;
 
+	set_real_ip_from 10.0.0.0/8;
+	set_real_ip_from 127.0.0.0/24;
+
 	# CloudFront IP addresses from http://d7uri8nf7uskq.cloudfront.net/tools/list-cloudfront-ips
 	# Last updated: 2022-03-26
 	set_real_ip_from 3.10.17.128/25;
@@ -148,22 +158,34 @@ http {
 	set_real_ip_from 223.71.71.96/27;
 	set_real_ip_from 223.71.71.128/25;
 
+    # Enable gzip compression of responses
 	gzip on;
+	# Set the gzip compression level to 2 (range: 1-9, nginx default: 1)
 	gzip_comp_level 2;
+	# Enable gzip compression for all proxied requests
 	gzip_proxied any;
+	# Set the minimum length of a response that will be gzipped. The length is determined only from the “Content-Length” response header field.
 	gzip_min_length 512;
+	# Enable gzip for responses with the specified MIME types in addition to “text/html”. Responses with the “text/html” type are always compressed.
 	gzip_types text/plain text/css application/json application/javascript application/x-javascript text/javascript text/xml application/xml application/rss+xml application/atom+xml application/rdf+xml image/svg+xml;
 
+    # Disable emitting nginx version on error pages and in the “Server” response header field
 	server_tokens off;
 
-	# Disable access logs, keep error logs on Heroku
+	# Disable access logs, since our axum application logs them too
 	access_log /dev/null;
+	# Write error logs to the default `heroku-buildpack-nginx` location
 	error_log logs/nginx/error.log;
 
+    # Define common file name extension to MIME type mappings
 	include mime.types;
+    # Define the default MIME type of a response if none of the mappings from above match
 	default_type application/octet-stream;
+
+	# Enable the use of the `sendfile` Linux API for sending files over the network
 	sendfile on;
 
+    # Set the maximum allowed size of the client request body to 50 MB
 	client_max_body_size 50m;
 
 	upstream app_server {
@@ -172,17 +194,31 @@ http {
 
 	server {
 		listen <%= ENV["PORT"] %>;
+
+		# Set a catch-all server name (see http://nginx.org/en/docs/http/server_names.html)
 		server_name _;
+
+        # Set a timeout during which a keep-alive client connection will stay open on the server side
 		keepalive_timeout 5;
 
+        # Use the passed-in `Host` header for proxied requests instead of changing it to the `proxy_pass` value
 		proxy_set_header Host $http_host;
+
+		# Add a `X-Real-Ip` header to proxied requests containing the client address
+		# (after being changed by the `realip` module)
 		proxy_set_header X-Real-Ip $remote_addr;
+
+		# Disable `Location` and `Refresh` header rewriting for proxied responses
 		proxy_redirect off;
+
+        # If the `X-Forwarded-Proto` request header does not contain `https` …
 		if ($http_x_forwarded_proto != 'https') {
+		    # … return a "301 Moved Permanently" response to the HTTPS equivalent URL
 			rewrite ^ https://$host$request_uri? permanent;
 		}
 
         location / {
+            # Proxy all requests to our axum app server
             proxy_pass http://app_server;
         }
 	}