The nginx location matching prayer/algorithm

A daily devotion for webmasters

My main nginx web server config is so complicated that many years ago I added the following comment block, copy-pasted from the docs.

# https://nginx.org/en/docs/http/ngx_http_core_module.html#location
#
# To find location matching a given request, nginx first checks locations
# defined using the prefixstrings (prefix locations). Among them, the
# location with the longest matching prefix is selected and __remembered__.
#
# Then regular expressions are checked, in the order of their appearance in
# the configuration file. The search of regular expressions terminates on
# the first match, and the corresponding configuration is used.
#
# If no match with a regular expression is found then the configuration of
# the prefix location __remembered__ earlier is used.
#
# If the longest matching prefix location has the “^~” modifier then
# regular expressions are not checked.

This is not a very complex algorithm but it is easy to forget a detail or two. And it is easy to become confused about how an nginx config with lots of location blocks works if you don’t fully understand the algorithm.

For example, what’s the significance of the order of prefix locations relative to regex locations? None! (iiuc)

Or that glorious ^~ modifier, what does it do? If the logest prefix match to a request has it then nginx does no regex matching—a handy trick and not just for performance optimization.

So perhaps like me you want to memorize these six sentences as a prayer and recite it daily to the ghost of Dijkstra, Lovelace, or the ghost of your choice because if you don’t know this prayer by heart then what are you doing editng an nxinx config?