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.
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.
/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>;
}
HTTPS and SSL
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.
}