Kahibaro
Discord Login Register ☰
☰
Previous
Up
Next

5.1.2 Nginx basics

Table of Contents

What Nginx Is and When to Use It

Nginx (pronounced “engine-x”) is a high‑performance, event‑driven web server and reverse proxy. In contrast to more process‑heavy servers, it is designed to handle very high numbers of simultaneous connections with low memory usage.

Typical uses:

In this chapter, we focus on core concepts and basic configuration you need to get a working Nginx setup on a Linux server.

Installing Nginx

Exact commands depend on your distribution’s package manager.

Debian/Ubuntu

sudo apt update
sudo apt install nginx

Default service management: 

sudo systemctl enable nginx
sudo systemctl start nginx
sudo systemctl status nginx

Default web root: /var/www/html
Default main config: /etc/nginx/nginx.conf

RHEL/CentOS/Rocky/Alma (DNF/YUM family)

Some distros require enabling EPEL or an nginx module; on current RHEL derivatives it is typically available directly: 

sudo dnf install nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Often the defaults are the same or very similar:

openSUSE

sudo zypper install nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Check distribution documentation if paths differ; the configuration structure is still the same conceptually.

Nginx Configuration Structure

Nginx uses a hierarchical configuration with:

Basic skeleton: 

# /etc/nginx/nginx.conf
user  www-data;
worker_processes auto;
events {
    worker_connections 1024;
}
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile on;
    # Include individual virtual host configs
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Key ideas:

Master and Worker Processes (High-Level)

Nginx uses:

Relevant directives (in nginx.conf):

Rough maximum concurrency:

$$
\text{max\_connections} \approx \text{worker\_processes} \times \text{worker\_connections}
$$

These are tuning topics, but you should recognize where they are defined and that they live in the global / events context, not per‑site.

Basic HTTP Server Block (Virtual Host)

Nginx uses server blocks (often called “virtual hosts”) to host multiple sites on one server.

Minimal HTTP example: 

# /etc/nginx/sites-available/example.conf
server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/example;
    index index.html index.htm;
    access_log /var/log/nginx/example.access.log;
    error_log  /var/log/nginx/example.error.log;
    location / {
        try_files $uri $uri/ =404;
    }
}

Common directives:

On Debian/Ubuntu, typical layout: 

  sudo ln -s /etc/nginx/sites-available/example.conf \
             /etc/nginx/sites-enabled/example.conf

On other distros, a common convention is simply: /etc/nginx/conf.d/example.conf (included from nginx.conf).

Location Blocks and URL Matching

location blocks control how Nginx handles different request paths.

Basic forms: 

location / {
    # matches everything (fallback)
}
location /images/ {
    # matches /images/... but not /img/...
}
location = /exact-path {
    # exact match for /exact-path
}

Common prefixes/operators:

Nginx chooses the best match based on a fixed order (exact > prefix > regex). When starting out, stick to simple prefix and exact matches.

Serving Static Files

A simple static site configuration: 

server {
    listen 80;
    server_name static.example.com;
    root /var/www/static.example.com;
    index index.html;
    location / {
        # 'root' from server context is used
        try_files $uri $uri/ =404;
    }
    # Serve files under /assets/ with caching headers
    location /assets/ {
        expires 7d;
        add_header Cache-Control "public";
    }
}

Key directives:

Basic Reverse Proxying

Nginx frequently sits in front of an application server (e.g., Gunicorn, uWSGI, Node.js, PHP-FPM). It accepts client connections and forwards them to the backend.

Minimal HTTP reverse proxy: 

upstream app_backend {
    server 127.0.0.1:3000;
    # you can list multiple servers here for load balancing
}
server {
    listen 80;
    server_name app.example.com;
    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Key pieces:

Without correct headers, your application may see all traffic coming from 127.0.0.1 instead of real client IPs.

Basic TLS/HTTPS Configuration

Nginx can directly terminate TLS; full certificate management is covered elsewhere, so here’s the minimal structure once you have keys.

Assuming: 

server {
    listen 443 ssl http2;
    server_name secure.example.com;
    ssl_certificate     /etc/ssl/certs/example.crt;
    ssl_certificate_key /etc/ssl/private/example.key;
    # Basic security/cipher settings will be covered in SSL/HTTPS chapter
    # but you need at least the above to bring TLS up.
    root /var/www/secure.example.com;
    index index.html;
    location / {
        try_files $uri $uri/ =404;
    }
}
# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name secure.example.com;
    return 301 https://$host$request_uri;
}

Important points:

Managing Nginx: Test, Reload, Restart

When editing configuration, never restart blindly on production. Use Nginx’s built-in config tester.

Test Configuration

sudo nginx -t

If everything is OK, you see something like: 

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If there are errors, output will indicate the file and line; fix and re-test.

Reload Without Dropping Connections

To apply changes gracefully: 

sudo systemctl reload nginx

Nginx will:

Restart

Use a restart only if necessary (e.g., crashed process, binary update): 

sudo systemctl restart nginx

Logging Basics

Nginx provides per-site logging; useful for debugging and analysis.

In a server block: 

access_log /var/log/nginx/example.access.log;
error_log  /var/log/nginx/example.error.log warn;

Common commands: 

# View latest access log entries
sudo tail -f /var/log/nginx/example.access.log
# View latest error log entries
sudo tail -f /var/log/nginx/example.error.log

Log formats can be customized globally in http { ... } using log_format but basic defaults are sufficient to start.

Common Beginner Pitfalls

Some frequent issues when starting with Nginx:

  1. Wrong server block chosen
    • Symptom: You hit the server in a browser and get the “Welcome to nginx!” page or the wrong site.
    • Check: server_name matches the requested hostname; order and default server configuration.
    • Hint: Use curl -H "Host: example.com" http://IP/ to test.
  2. File permission errors
    • Symptom: 403 Forbidden for static files.
    • Cause: Nginx worker user (e.g., www-data, nginx) cannot read files.
    • Fix: Ensure directory and file permissions allow read (r) and execute (x on directories) for the Nginx user or group.
  3. Forgetting to reload after config change
    • nginx -t then systemctl reload nginx after every change.
  4. Port already in use
    • Symptom: Nginx fails to start; error log mentions bind() to 0.0.0.0:80 failed.
    • Cause: Another service is listening on that port (perhaps Apache).
    • Fix: Stop/disable the other service or change Nginx port.
  5. Proxying without proper headers
    • Symptom: Application logs show 127.0.0.1 as client IP for everything.
    • Fix: Add proxy_set_header X-Real-IP and X-Forwarded-For in proxy location.

Basic Hardening Steps (Overview Only)

Full web hardening is covered elsewhere, but minimal Nginx-specific basics: 

  # in http { ... }
  server_tokens off;
  location ~ /\. {
      deny all;
  }

These are starting points; a proper hardening strategy goes much further.

Quick Checklist: Bringing Up a Simple Site

  1. Install Nginx via your distro package manager.
  2. Create web root, e.g.:
   sudo mkdir -p /var/www/example
   sudo chown -R $USER:$USER /var/www/example
   echo "Hello from Nginx" > /var/www/example/index.html
  1. Create server block in /etc/nginx/sites-available/example.conf (or conf.d/).
  2. Enable the config (symlink or ensure it’s included).
  3. Test configuration: sudo nginx -t.
  4. Reload Nginx: sudo systemctl reload nginx.
  5. Test from client: curl http://example.com or via browser.

Once you’re comfortable with these basics, you can move on to using Nginx for virtual hosts, SSL/TLS, reverse proxying to app servers, and more advanced features.

Previous
Up
Next

Views: 78

Comments

Please login to add a comment.

Don't have an account? Register now!

© 2025 Kahibaro

Visitors: 4242 / 24h

Impressum / Imprint

Datenschutz / Data Policy