Programming/Nginx

Nginx started off as a lightweight Web Server that has since grown to be suitable for more use cases.

As far as being used as a web server, Nginx is generally comparable to Apache.

Documentation on this page is primarily for using Nginx as a web server.

Note: For the following page, make sure to replace all values in pointy brackets. Ex: Every instance of <project_name> should be replaced with your project's actual name.

Nginx Files & Management

Note that any time a config file is added, remove, changed, or the Nginx server is otherwise updated, the Nginx server will need to be restarted via:

sudo systemctl restart nginx

Check for errors with:

sudo nginx -t

If any errors occur, then it might be helpful to run journalctl -xe which may possibly give more detailed output (depending on the error).

Config Files

Generally speaking, each project (or group of related projects) will have it's own .conf file, located at /etc/nginx/sites-availabile.

To enable a config file, create a Sym Link from /etc/nginx/sites-available/<project>.conf to /etc/nginx/sites-enabled/<project>.conf. Then restart the Nginx server.

To disable a config file, delete the sym link at /etc/nginx/sites-enabled/<project>.conf. Then restart the Nginx server.

Warn: By default, there is probably a "default" config file under /etc/nginx/sites-enabled/. You can safely remove this file, as it's effectively being replaced by your own config. Furthermore, leaving this default may cause issues and override values in any config you create.

Snippet Files

Snippets are files that contain smaller chunks of reusable code, and are meant to be included in the config files. Snippet files are (generally) stored at /etc/nginx/snippets/.

Nearly anything can go into a snippet, so there's no hard rule on what should go into the file itself. One common use is to put the server's SSL certificate information in a snippet, then include that snippet in all config files.

The syntax to include a snippet file is as follows:

include <path_to_snippet_from_nginx_folder>;

For example, for a SSL cert snippet, we may have:

include snippets/ssl_certs.conf;

General Config Syntax

Comments

# This is an inline comment.

Server Block

The "core" of Nginx syntax is the server block.

At their simplest, these blocks essentially specify the incoming server name (or IP address), the port to listen on, and then how to handle requests.

/etc/nginx/sites-available/<project_name>.conf

server {

    # Base settings.
    server_name <server_name>;
    listen <port_number>;

    # Put request handling here.

}

Location Blocks

A location block is put within a server block. Essentially, a location block specifies how to handle the respective url.

General syntax is as follows:

/etc/nginx/sites-available/<project_name>.conf

server {

    ...

    location /<url_to_handle> {
        # Logic here for given url.
    }

    ...

}

Example 1: Serving static

To serve "static" content, such as CSS or images.

This example will handle anything with a website url of example.com/static:

/etc/nginx/sites-available/<project_name>.conf

    # Serve static files.
    location /static {
        alias <path_to_static_file_location>;
    }

Example 2: Redirecting Specific Requests

To redirect a specific request url to a different url, use the following:

/etc/nginx/sites-available/<project_name>.conf

    # Redirect url.
    location /some_url_to_redirect {
        return 302 <full_url_to_redirect_to>;
    }

Example 3: Passing Requests to UWSGI

To pass request handling off to UWSGI, such as for serving a Programming/Django.

This example will handle anything with a website url of example.com/stuff:

/etc/nginx/sites-available/<project_name>.conf

    # Serve Django project request.
    location /stuff {
        include uwsgi_params;
        uwsgi_pass unix:/run/uwsgi/<project_name>.sock;
    }

See Programming/Django for more details on setting up UWSGI.

Reusable Location Blocks

Consider the above Example 3. Consider if you have a Django project where you want to handle multiple unique URLS with the same UWSGI socket.

We can reduce redundancy by defining this location handler once:

/etc/nginx/sites-available/<project_name>.conf

    # Define logic for serving Django project.
    location @<project_name> {
        include uwsgi_params;
        uwsgi_pass unix:/run/uwsgi/<project_name>.sock;
    }

Then for our url handling, we can reference this code with the following:

/etc/nginx/sites-available/<project_name>.conf

    # Grab urls for Django Project.
    location /my_location_1 {
        try_files $uri @<project_name>;
    }
    location /my_location_2 {
        try_files $uri @<project_name>;
    }

Note: For this to work, it seems that the "try_files" syntax definitions need to be placed before the @<project_name> syntax definition.

HTTPS and SSL

ToDo: Document making server more secure with possible SSL params.

Generally speaking, one of the first things to configure on an Nginx server should be SSL and secure connections.

As long as the server has a domain name, then SSL certificates are easy and free to acquire through LetsEncrypt.

Create SSL Snippet for Nginx

Create a snippet for easy including in all Nginx config files.:

/etc/nginx/snippets/ssl_certs.conf

ssl_certificate <ssl_certificate_location>;
ssl_certificate_key <ssl_certificate_key_location>;

Note that these values should be the absolute path on the server for the SSL certificate and SSL key, respectively.

Redirecting HTTP to HTTPS

Once certificates are created, Nginx should probably be configured to redirect all HTTP to HTTPS.

Note that the below code is all that's needed for SSL redirecting. It unconditionally redirects all requests to use HTTPS, which are then handled by a different server block.

/etc/nginx/sites-available/<project_name>.conf

# Insecure connection configuration.
server {

    # Base settings.
    server_name <server_name>;
    listen 80;

    # Redirect all requests.
    return 302 https://$host$request_uri;

}

Serving with HTTPS

When serving with SSL, you'll need a server block to specifically handle the HTTPS requests:

/etc/nginx/sites-available/<project_name>.conf

# Secure connection configuration.
server {

    # Base settings.
    server_name <server_name>;
    listen 443 ssl;

    # SSL settings.
    include snippets/ssl_certs.conf;

    # Put request handling here.

}