Nginx

What is Nginx?

Nginx is primarily a web server and reverse proxy:

• As a web server: It can serve static content like HTML, CSS, or image files directly from your filesystem to the web browser.
• As a reverse proxy: It can sit between your web server and the Internet. It can look at an incoming request and based on the configuration you’ve set up, it can forward some requests to other servers and applications (e.g., forward requests to a PHP or Ruby application) to obtain a HTTP response and return that back to the web browser.
• As a load balancer: It can distribute incoming network traffic across multiple servers or applications to prevent a single server from becoming overloaded.
• For caching: It can store frequently accessed files in memory to reduce load on servers and to speed up content delivery.
• For security: It can support basic HTTP authentication, IP-based restriction, and other features.

Configuring Nginx’s behaviour

You create a .conf file (typically at /etc/nginx/nginx.conf) to define configuration for your server. This is made up of directives (key-value pairs) and groups of directives called contexts.

You can create a separate configuration for each server where each server is distinguishable by the port it listens on.

You typically configure a server as either a web server to serve files directly or as a reverse proxy (forward requests to another application on your server to handle).

Example Nginx projects

• Static HTML, CSS, and JavaScript app
• Plain PHP app
• Symfony PHP project
• WordPress PHP project

Server configuration

server

access_log

TODO

add_header

Add a HTTP response headers to outgoing HTTP responses.

Example:

add_header X-Custom-Header Hello-World always

listen (Port)

The port on the server that your application is listening on (e.g., 80, 443, etc).This is almost always either 80 (HTTP) or 443 (HTTPS)

location

Sets configuration depending on the request URI. Here, we’re telling Nginx to resolve all requests by first trying to serve a file that matches the URI ( e.g., try serving /var/www/example/foo/bar.png for requests to http://example.test/foo/bar.png). Failing this, it should try to serve an index file at the URI (e.g., serve /var/www/example/foo/index.html for requests to http://example.test/foo). If both methods fail, it should return a 404 not found response.

error_log

TODO

index

Defines what files should be used as an index.

location

Applies configuration based on the request URI. A location can be defined via an exactstring, prefix string or a regular expression.

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

For the above configuration, the “/” request will match configuration A, the “/index.html” request will match configuration B, the “/documents/document.html” request will match configuration C, the “/images/1.gif” request will match configuration D, and the “/documents/1.jpg” request will match configuration E.

return

Redirect requests.

Example: Redirect all HTTP requests to port 80 to port 443 (HTTPS):

root

Sets the root directory for the request.

try_files

Uses the first file found in the given list to process the incoming request.

Example:

location / {
  try_files $uri $uri/ /index.php$is_args$args;
}

The above will cause Nginx to:

• Try to serve the exact file request by the URI. For example, if the URI is /about.html, try serving that file from the filesystem.
• If that file doesn’t exist, try to serve the directory. For example the the URI is /about, try serving /about/<index> where <index> is the index files you configure via the index directive.
• If neither the file nor an index at the directory exists, internally rewrite the request to /index.php and pass the query string.
  • $is_args will be converted to ? if there were query parameters in the original request of an empty string if there were none.
  • $args will be converted to the actual query parameters from the original request.

Let’s consider an example request for:

GET /about-us?lang=en

With the try_files config from earlier, Nginx will do the following:

• Try and serve the file /about-us if it exists in the file system at the given root location (see the root directive).
• Try and serve /about-us/<index-files> if it exists.
• If the above fails, rewrite the request internally to /index.php?lang=en.

sendfile

Can either be on or off.

If on, Nginx will use the operating system’s sendfile() system call to transfer file contents directly from the disk to the network socket, without copying the file into user space.

server_name

What domain name this server block applies to. In other words, we only want to apply the rules inside this server block to requests to http://example.test.

Links

• Alphabetical index of directives