Saving bandwidth and increasing throughput using compression
This note describes how to configure the server to compress files while in transit between the server and browser.
File compression is an easy way to increase performance: fewer bytes, faster response times. File compression is supported by all browsers, and most third-party HTTP utilities. It is safe and should be enabled in most production scenarios.
The server supports three compression algorithms: deflate, gzip and brotli. For most text files, brotli is the best choice. For other uncompressed file types, gzip is a good choice.
Compression is most useful on text media. Binary media, including images, audio, and video, are already compressed using their own algorithms, and attempting to compress them further with gzip or deflate provides very little improvement, and in some cases actually increases file size. Note that SVG images are actually text files, and they do benefit from compression.
Small files do not benefit from compression. This is due to the fact that data transmission through the TCP/IP stack is governed by the Ethernet MTU (Maximum Transmission Unit) size of 1500 bytes, so that responses, where the HTTP headers plus payload is less than the MTU, do not improve network throughput. The typical size of response headers varies, but with HTTP/2 HPACK header compression it can be relatively small, say 100 bytes. If the file being served is smaller than the MTU minus HPACK headers, there is no need to compress. The server uses a fixed value of 1400 bytes as the threshold for compression, and will not gzip or deflate files smaller than that threshold.
Compression is negotiated between the browser and server with the
accept-encoding request header. When an incoming request is recieved by the server, it looks for that header and determines whether or not it can fulfill the request using any of the listed algorithms. If it can, and if the configuration allows it, the response payload is compressed and a
content-encoding header is added to the response indicating which algorithm was chosen.
Server compression is enabled by adding an entry to the
modules section with
content-encoding set to
on. During development and while troublshooting problems, this can be set to
off and the rest of the configuration related to compression will be ignored.
Compression is configured on a MIME-type basis. The
content-encoding configuration section specifies, by content type, which compression algorithm to use. It comprises a collection of two-part entries: the left hand side is the MIME-type, and the right-hand side is a comma-separated list of acceptable compression algorithms, with best choice first.
Compression will only occur when all four of these conditions are true:
- The browser has included an
accept-encodingheader with a value that specifies
- The MIME-type of the requested file is configured with an algorithm that matches one of the requestor's values.
- The file is larger than 1400 bytes.
content-encoding configuration section may appear in either the
server section or a
host section. When values occur in both the
host sections, they are merged according to the standard rules defined for the
|media-type||::=||'text' | 'application' | 'image'|
|subtype||::=||(ALPHA | DIGIT | †)*|
|MIME-type||::=||media-type SOLIDUS subtype|
|compression-algorithm||::=||'br' | 'gzip' | 'deflate' | 'none'|
|content-encoding-entry||::=||MIME-type SP compression-algorithm CR|
|content-encoding-section||::=||'content-encoding' SP LEFT-CURLY-BRACKET CR|
† See section 4.2 of RFC 6838 for exact rules
Example 1: Content encoding best practice
// any MIME-type not explicitly set to 'none'
Example 2: Content encoding turned off for debugging
Key points to remember:
- Compression is safe and effective. It should always be turned on in production.
content-encodingsection associates MIME-types with compression algorithms.
- Binary files should not be compressed.