location = / is very tricky

[Дилян Палаузов]

After reading ​http://nginx.org/en/docs/http/ngx_http_core_module.html#location I created a contiguration:

server {
  server_name a.local;
  root /a;
  location = / {
    root /b;
  }
}

My understanding from the documentation is, that calling ​http://a.local/z will return /a/z, but calling ​http://a.local/ will return /b/index.html. This does not happen. I changed the configuration to

server {
  server_name a.local;
  root /a;
  location = /index.html {
    root /b;
  }
}

Now, if /a/index.html exists, calling ​http://a.local/ returns /b/index.html, but if /a/index.html does not exist, then /b/index.html is not returned.

The documentation at nginx.org/en/docs/http/ngx_http_index_module.html makes things even more complicated. The value of the index directive is by default "index.html" and it seems impossible to delete the default value. Having this into account (the index-directive always has a value), location = / never matches

• clarify how to change the root for the =/ request, when the file /index.html does not exist, but the request ​http://a.local/ is valid
• Unify the documentation for the index and location directives, say how to remove the value for index for a specific server{} and how to match exactly only the server_name/ request.

[Maxim Dounin]

My understanding from the documentation is, that calling ​http://a.local/z will return /a/z, but calling ​http://a.local/ will return /b/index.html. This does not happen.

Your understanding is wrong. Requesting http://a.local/ will trigger an internal redirect to /index.html as long as /b/index.html exists. Since your configuration does not contain a location configured for /index.html, after the redirection the request will processed in the default location and will try to return /a/index.html as per root in the server block.

Consider reading the ​How nginx processes a request introductory article, hopefully it will help you to better understand how to configure nginx in various non-trivial cases like the one you are trying to configure. If you still have question, consider using ​support options available.