Introduction

Nginx is a fast, lightweight, high performance web server that makes it easy to deploy websites. It has virtual web pages so you can have several websites at a single IP/port pair. With less features, it's easier to use.

Interpreting Locations

NOTE:

Once you've read this section, for a deeper understanding of locations you should read Triple Site Example.

This section barely scratches the surface, but gives you enough info that you won't waste hoursendlessly circling dead ends. A location block's declaration looks like the following:

location 
   <optional modifier> 
   <required location match string>
   <optional flag> {
      <Stuff to do if matched>
}

Typically the modifier, location match string, flag and opening brace are placed on a single line, but I used separate lines for the convenience of those viewing this on a small device.

Location blocks often resemble some of the following:

location ~* /todo.otl {

location / {

location /donuts {

See the forward slash in each one? In computer science, forward slashes are regularly used as:

File path separator
URL separator
Structural element of a regular expression.

Always remember that as used in an nginx location block, the forward slash is a URL separator and only a URL separator. If you forget that, all is lost. Nothing in the location match string has anything to do with directories: It's about URLs exclusively. Sometimes you can get lucky because in a lot of simple, static, old-school websites the URL structure mirrors the directory structure. But take it from me: It's the kiss of death to think anything in the location match string has anything todo with directories or regex separators: The location match string is about the URL and nothing else.

Specifically, it's about the part of the URL that follows the domain name.

The optional modifier determines how locations are searched. They can be searched no-regex exactly (=), regex case sensitive (~), regex case INsensitive (~*), or a prefix match (no modifier at all), which means the entire location match string must match beginning of the after-domain-name URL, and if the URL has characters after the end of the match, it's still a match.

The flag is beyond the scope of this section and is discussed a little bit later in this document.

For a much more complete story on location matching (and incidentally server matching too), see DigitalOcean's complete treatise at https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms.

And if you remember nothing else from this section, remember that in location matches, slashes are URL separators exclusively, and the location match string is matched exclusively against the post-domain-name portion of the incoming URL.

For a deeper understanding of locations, see Triple Site Example.

View As Text

Let's say you want to serve up a .otl file and have it show up in all servers as plain text, without asking the user what to do with it. To do this with a single website (server block in nginx language), insert the following within the server{} block, or even in a location{} block if you need it only on very specific web pages:

types {
   text/plain otl;
}

INSUFFICIENT INFORMATION ALERT!

Please read the next paragraph about the content of types{}.

Something's odd. In the previously described types{} statement, you can substitute anything whose first 4 letters are "text" for the text/plain shown previously, and it will perform as if you had put text/plain. This is bizarre, I don't know why it happens, it sounds like bad mama-jama to me, so don't take advantage of it. Use text/plain for this purpose.

From my testing, it appears you can put it anywhere in the server{} block as long as it's not inside anything else (like a location{} section). But if things go wrong, try placing it in a different position.

I really don't recommend this, but there's a way to do this for all server blocks. Within /etc/nginx/mime.types search for the line containing text/plain. Just before the semicolon at the end of this line, insert a space followed by otl, and all your servers will serve up .otl files as plain text. As mentioned, I don't recommend this.:

Eliminating Caching from a File

Nothing's more frustrating during debugging than having cached results show up after server or html file changes that would have changed the browser's picture if the browser hadn't used a cached copy in full faith. With nginx, the best way I've found is to use the elinks text browser. It can't cache, do it doesn't.

FAILURE ALERT:

Note that with HTML files served by Apache, you might be able to use the following header line to prevent caching on all browsers:

<META HTTP-EQUIV="pragma" CONTENT="nocache">

I have found nothing that performs the same function on a non-HTML file served by nginx.

Run Nginx On a Terminal

In normal production operation, nginx is run by the init system. But when you're developing, be sure to run it on a terminal (as root), so that you can see any error messages. The command is as follows:

nginx -g 'daemon off;'

Init Setup for Nginx

The following is the runit run file for nginx:

#!/bin/sh
exec nginx -g 'daemon off;'

If you were to use a non-default config filename or pass some directives other than 'daemon off;', it would change accordingly. The run files for init s6 and process supervisor daemontools would be similar.

An init system or process supervisor can start daemons in one of two ways:

Init system asks the program to background itself
Init system backgrounds the program

Sysvinit and Epoch are #1. Daemontools, daemontools-encore, runit, s6 and Perp are #2. OpenRC and systemd can go either way, but recommend #2 if possible. In my opinion #2 is much cleaner.

If you're using method #2, you need to tell nginx not to background itself. You do that by adding the argument -g 'daemon off;' to the nginx call.

If you're using method #1, in your init script or whatever you need to tell nginx to background itself, which is the default behavior for nginx. So in the #1 case, leave out the -g 'daemon off;' argument.

[ Training | Troubleshooters.Com | Email Steve Litt ]