diff --git a/doc/TOC.md b/doc/TOC.md index 7e83cac..077f1f5 100644 --- a/doc/TOC.md +++ b/doc/TOC.md @@ -6,6 +6,7 @@ * [Usage](usage.md) — Overview of the project contents. * [Nginx.conf](nginx-conf.md) —General introduction to the main config file. +* [How Nginx works](how-nginx-works.md) —Understanding nginx, and how it differs from other webservers. * [Common problems](common-problems.md) —Dealing with commonly-encounterederrors. ## Related projects diff --git a/doc/how-nginx-works.md b/doc/how-nginx-works.md new file mode 100644 index 0000000..1c275b1 --- /dev/null +++ b/doc/how-nginx-works.md @@ -0,0 +1,41 @@ +[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx) + | [Documentation table of contents](TOC.md) + +# How Nginx works + +If you're familiar with any other webserver, some aspects of +[the way Nginx works](http://nginx.org/en/docs/http/request_processing.html) + can cause confusion. This document aims to highlight differences or features +which may trip up new users. + +## Nginx will only use one location block + +A [location block (directive)](http://nginx.org/en/docs/http/ngx_http_core_module.html#location) +defines the behavior for a given request which matches the location url pattern. + +It is very important when writing nginx configuration files to understand that +only one location block will be used by Nginx. When in doubt a useful technique +to identify which location block is to add a header: + + # Make sure js files are served with a long expire + location ~ /something { + add_header "section" "something location"; + + ... + } + + location /something-else { + add_header "section" "something else location"; + + ... + } + +In the headers for a response, the header added from the block which matched +will be included: + + $ curl -I "http://nginx.h5bp.dev/something" + ... + section: something location + +There are some significant concequences to this behavior such as it _not_ being +possible to build configuration files from small, overlapping, location blocks.