How to understand your NGINX server configuration

This is the first of a series of guides to help you prepare to become an NGINX Super User. You can sign up for the NGINX Super User Challenge at the bottom of the page.

Web server, load balancer and API Gateway are just a few of the use cases that can be met with NGINX's open source and NGINX+ servers. Here's how to locate and understand the configuration logic.

NGINX can run anywhere: on any cloud provider, bare metal, on your laptop. And NGINX runs exactly the same whether you as a developer are running it on your laptop or someone's running it in a cloud provider.

Topics covered in this guide:

This guide shows how to:

• Execute basic NGINX commands
• Locate your NGINX configurations
• Understand the role of context and blocks

Want to install NGINX?

If you would like to follow along the demo, you can install NGINX on your own laptop, server or cloud provider using these methods. If you need help installing, click the image to watch the video "How to get started with NGINX"

Basic commands:

These are the basic commands you use to interact with your NGINX instance.

Check NGINX version:

$ nginx -v                  /* prints the version of nginx */

Check configuration file syntax before reloading:

$ nginx -t                  /* validates the syntax to ensure that there are no issues with the configuration you're about to push */

Display current configurations:

$ nginx -T                  /* gives you the configuration which is currently implemented in your instance of nginx */

Reload NGINX

$ nginx -s reload           /* takes the configuration and pushes it out to the existing instance */

Configuration file locations:

The default location of your nginx.conf configuration file is the /etc/nginx directory.

Main File:

/etc/nginx/nginx.conf

The best way to configure your nginx instance is by putting all your personalised configurations into the config.d directory. You use the include directive in your main nginx file to go out and access all those configurations.

Includes:

/etc/nginx/conf.d/*.conf

Configuration Contexts:

The configuration file consists of combinations of contexts and directives.

Each NGINX configuration has:

• One Main context
• One HTTP context.

The Main context is the very highest level where you declare the highest level directives, such as:

• The number of worker processes
• The linux username
• The location of the Process ID (PID) file
• The location of the log file

The Events context is used to define the connection processing directives; that is the number of connections assigned to each worker process.

The HTTP context defines how NGINX processes the http and https connections. For example, we can set a pool of backend servers or applications.

Directives used on the HTTP context are inherited by its children contexts; that is the Upstream, the Server and the Location contexts. The Server context defines a virtual server so it's also known as virtual host, which processes a given http request for:

• Domain name
• IP address
• Unix socket

The Location context further defines how the virtual server processes an http request based on the specific URI you've defined. It can point to a path on the file system, or be determined by matching the URI request to a string defined in the context.

The Upstream context defines a group of backend applications, application servers or web servers to use in a load balancing use case.

The Stream context defines how NGINX handles the Layer 3 and Layer 4 traffic such as TCP and UDP.

Directives and Blocks:

We use directives to achieve a specific functionality within your NGINX configuration.

A directive is a single statement that controls a given NGINX behaviour.

A block is a group of directives encased in curly braces.

What we see on the screen here is a listen directive telling NGINX to listen on port 80, and the root directive is pointing to a path in the file system.

So all these contexts and directives are defined in the configuration file to look something like the image below.

Putting it all together

In this guide, we covered how to:

• Execute basic NGINX commands
• Locate your NGINX configurations
• Understand the role of context and blocks

This is the foundation on which all NGINX configurations are built.

In subsequent guides, we will cover configuring NGINX as a:

• Reverse Proxy
• Load Balancer
• Instance Manager
• API Gateway
• Kubernetes Ingress Controller
• Web Application Firewall (NGINX App Protect)

Want to watch the full guide?

In this video, NGINX's Senior Solution Engineer Jay Desai walks through the configuration and context logic, then shows a live demo of the configuration of an NGINX instance.

Have you signed up for the NGINX Super User Challenge?

Are you a full stack developer, engineer or API designer? Do you know how to build an API Gateway, load balancer or reverse proxy?

Become an NGINX Super User to showcase your knowledge and expertise.

Learn more at: https://apiconnections.co/blog/2022-05-25-nginx-super-user-challenge