replacing everything with more descriptive comments

for people that don't know what the options do

nginx/nginx.conf

@@ -1,4 +1,4 @@
-# Set another default user than root for security reasons
+# Run as a less privileged user for security reasons.
 user www www;
 
 # How many worker threads to run; "auto" sets it to the number
@@ -10,26 +10,27 @@ user www www;
 # max_clients = worker_processes * worker_connections
 worker_processes auto;
 
-# Maximum file descriptors that can be opened per process
-# This should be > worker_connections
+# Maximum open file descriptors per process;
+# should be > worker_connections.
 worker_rlimit_nofile 8192;
 
 events {
   # When you need > 8000 * cpu_cores connections, you start optimizing
   # your OS, and this is probably the point at where you hire people
-  # who are smarter than you, this is *a lot* of requests.
+  # who are smarter than you, as this is *a lot* of requests.
   worker_connections 8000;
 }
 
-# Change these paths to somewhere that suits you!
-error_log logs/error.log;
-pid logs/nginx.pid;
+# Default error log file (this is only used when you don't override error_log on a server{} level)
+error_log  logs/error.log warn;
+pid        /var/run/nginx.pid;
 
 http {
-  # Set the mime-types via the mime.types external file
-  include mime.types;
+  # Hide nginx version information.
+  server_tokens off;
 
-  # And the fallback mime-type
+  # Define the mime types for files.
+  include       /etc/nginx/mime.types;
   default_type  application/octet-stream;
 
   # Format for our log files
@@ -37,28 +38,37 @@ http {
     '"$request" $body_bytes_sent "$http_referer" '
     '"$http_user_agent" "$http_x_forwarded_for"';
 
-  # Click tracking!
+  # Default log file (this is only used when you don't override access_log on a server{} level)
   access_log logs/access.log main;
 
-  # Hide nginx version
-  server_tokens off;
-
-  # ~2 seconds is often enough for HTML/CSS, but connections in
-  # Nginx are cheap, so generally it's safe to increase it
+  # How long to allow each connection to stay idle; longer values are better
+  # for each individual client, particularly for SSL, but means that worker
+  # connections are tied up longer. (Default: 65)
   keepalive_timeout 20;
 
-  # You usually want to serve static files with Nginx
+  # Speed up file transfers by using sendfile() to copy directly
+  # between descriptors rather than using read()/write().
   sendfile        on;
 
-  tcp_nopush on; # off may be better for Comet/long-poll stuff
-  tcp_nodelay off; # on may be better for Comet/long-poll stuff
+  # Tell Nginx not to send out partial frames; this increases throughput
+  # since TCP frames are filled up before being sent out. (adds TCP_CORK)
+  tcp_nopush      on;
 
-  # Enable Gzip:
+  # Tell Nginx to enable the Nagle buffering algorithm for TCP packets, which
+  # collates several smaller packets together into one larger packet, thus saving
+  # bandwidth at the cost of a nearly imperceptible increase to latency. (removes TCP_NODELAY)
+  tcp_nodelay     off;
+
+  # Enable Gzip compressed responses from the server to massively speed up
+  # resource transfer times, especially for clients on slow connections.
+  # All browsers since ~1998 support Gzip compression.
   gzip on;
-  gzip_http_version 1.0;
-  gzip_comp_level 5;
-  gzip_min_length 512;
-  gzip_proxied any;
+  gzip_http_version  1.0; # enable compression both for HTTP/1.0 and HTTP/1.1, required for CloudFront
+  gzip_disable       "msie6"; # disable gzipping for ie 5.5 and ie 6
+  gzip_comp_level    5; # level is from 1-9; 5 is a perfect compromise between size and cpu usage, offering about 75% reduction for most ascii files (almost identical to level 9)
+  gzip_min_length    256; # don't compress anything that's already tiny and unlikely to shrink much if at all (the default is 20 bytes, which is bad as that usually leads to larger files after gzipping)
+  gzip_proxied       any; # compress data even for clients that are connecting to us via proxies (identified by the "Via" header), required for CloudFront
+  gzip_vary          on; # tells proxies to cache both the gzipped and regular version of a resource whenever the client's Accept-Encoding capabilities header varies; avoids the issue where a non-gzip capable client (which is extremely rare today) would display gibberish if their proxy gave them the gzipped version
   gzip_types
     # text/html is always compressed by HttpGzipModule
     text/css
@@ -76,12 +86,9 @@ http {
 
   # This should be turned on if you are going to have pre-compressed copies (.gz) of
   # static files available. If not it should be left off as it will cause extra I/O
-  # for the check. It would be better to enable this in a location {} block for
-  # a specific directory:
+  # for the check. It is best if you enable this in a location{} block for
+  # a specific directory, or on an individual server{} level.
   # gzip_static on;
 
-  gzip_disable "msie6";
-  gzip_vary on;
-
   include sites-enabled/*;
 }