A short course on nginx

Nginx: location and proxy_pass

Two rules decide which block a request lands in and what path the backend eventually sees: the order in which nginx evaluates location blocks, and the way proxy_pass assembles the upstream path. Every result quoted here was measured on nginx 1.27.5 inside an nginx:1.27-alpine container rather than taken from another document.

Start reading → Open the lab

Why this course is plain multi-page HTML Each lesson has a real address such as /en/lessons/location.html, so a crawler can index the lessons individually. Courses built on # routing collapse into a single indexable address; measured on one of them, requesting /hnsw returns 404 because the host has no path fallback.

The two lessons

Ten to fifteen minutes of reading each, with a lab that runs in the browser.

Lesson 1

How nginx picks a location block

Five steps in a fixed order, with a lab that takes your own configuration and path and agrees with 14 measurements from a real nginx.

Lesson 2

proxy_pass and the trailing slash

Four spellings, four different upstream paths. One of them concatenates two strings into a path that does not exist.

How the measurements were taken

Each lesson runs an nginx:1.27-alpine container with a cut-down configuration in which every location block returns its own name, then calls curl for each path to see which block won. Whatever a path returned is what the lesson records.

docker run -d --name nglab -p 8099:80 \
  -v "$PWD/default.conf:/etc/nginx/conf.d/default.conf:ro" \
  nginx:1.27-alpine

curl -s http://localhost:8099/img/a.gif
# 3 regex-gif-jpg

Running the configuration also catches configuration errors. While assembling lesson 1, nginx refused to start with duplicate location "/images/": ^~ /images/ and /images/ are the same block, because a modifier does not create a separate one. The two lines look like two different blocks, so the difference only shows up when nginx parses the file.