Serving Static Content

1. Configuring Root Directory

Directive	Values	Description
root	`/var/www/html`	Sets the root directory for requests
alias	`/var/www/`	Replaces the matched location with the specified path

Example: Setting Root Directory

server {
    listen 80;
    server_name example.com;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Note: The root directive appends the location path to the root directory. For example, a request to /images/ will look for files in /var/www/html/images/.

Warning: Ensure proper file permissions for the root directory to allow Nginx to read files.

2. Using Alias Directive

Directive	Context	Description	Example
alias	location	Maps a URL prefix to a file system path. Unlike `root`, it replaces the matched part of the URL.	`location /images/ { alias /var/www/images/; }`

Example: Serving Images with Alias

server {
    listen 80;
    server_name example.com;

    location /images/ {
        alias /var/www/images/;
    }
}

Note: When using alias, the path specified is the actual file system path. If a request matches /images/logo.png, it will serve the file at /var/www/images/logo.png.

3. Setting Index Files

Directive	Values	Description
index	`index.html`	Specifies the default file to serve when a directory is requested
index	`index.htm`	Alternative default file for HTML content

Example: Basic Index File Configuration

server {
    listen 80;
    server_name example.com;

    location / {
        index index.html index.htm;
    }
}

4. Enabling Directory Listing

Directive	Values	Description
autoindex	`on` \| `off`	Enables or disables directory listing. Default is `off`.
autoindex_format	`html` \| `json` \| `xml`	Specifies the format of the directory listing. Default is `html`.
autoindex_exact_size	`on` \| `off`	Displays file sizes in bytes if `on`, otherwise uses human-readable format. Default is `on`.
autoindex_localtime	`on` \| `off`	Displays file times in local time if `on`, otherwise uses UTC. Default is `off`.

Example: Enabling Directory Listing

location /static/ {
    autoindex on;
    autoindex_format html;
    autoindex_exact_size off;
    autoindex_localtime on;
}

Note: Directory listing is useful for debugging or providing public access to files, but should be restricted in production environments.

5. Customizing Autoindex

Directive	Values	Description
autoindex	`on` \| `off`	Enables or disables directory listing. Default is `off`.
autoindex_format	`json` \| `xml` \| `html`	Sets the format of the autoindex output. Default is `html`.
autoindex_exact_size	`on` \| `off`	Displays file sizes in bytes if `on`. If `off`, uses human-readable format (e.g., K, M). Default is `on`.
autoindex_format	`html` \| `json` \| `xml`	Specifies the format of the autoindex page. Default is `html`.
autoindex_localtime	`on` \| `off`	Displays times in local time if `on`. If `off`, uses UTC. Default is `off`.

Example: Enabling and Customizing Autoindex

location /static/ {
    autoindex on;
    autoindex_format html;
    autoindex_exact_size off;
    autoindex_localtime on;
}

Note: The autoindex directive is useful for serving directory listings, but should be used carefully in production environments due to security implications.

6. Setting File Permissions

Permission	Description	Example	Notes
owner	User who owns the file	`nginx`	Typically set to the user running the Nginx process
group	Group that owns the file	`nginx`	Should match the user or be a shared group
read	Read access to file content	`4`	Allows reading of static files (e.g. HTML, CSS, JS)
write	Write access to file content	`2`	Not required for static content, but needed for logs or cache
execute	Execute permission (for directories)	`1`	Required for directories to allow traversal

Example: Setting File Permissions

sudo chown -R nginx:nginx /var/www/html
sudo chmod -R 644 /var/www/html
sudo chmod -R 755 /var/www/html/assets

Note: Ensure that the Nginx user has read access to all static files. Write permissions should be restricted to avoid security risks.

7. Configuring Expires Headers

Directive	Values	Description
expires	`1d`, `1h`, `1m`, `1s`, `epoch`, `off`	Sets the Expires header for static content. Supports time units (d=days, h=hours, m=minutes, s=seconds) or `epoch` for past date or `off` to disable.
expires_by_type	Media type → `time`	Applies different expiration times based on MIME type. E.g., `text/css 1y`.

Example: Setting Expires Headers for Static Assets

location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Example: Using expires_by_type for Different Media Types

expires_by_type text/css 1y;
expires_by_type application/javascript 1y;
expires_by_type image/png 1M;
expires_by_type image/jpeg 1M;

Note: The expires directive sets the Expires header, while Cache-Control is often preferred for more granular control.

Warning: Setting very long expiration times (e.g., 1y) can cause issues when content is updated. Use with caution in production.

8. Adding Cache-Control Headers

Directive	Description	Values	Notes
expires	Sets the Expires header	`1d`, `1h`, `30m`	Can be relative or absolute date/time
add_header Cache-Control	Adds Cache-Control header to response	`max-age=31536000`, `public`, `no-cache`	Used for fine-grained cache control

Example: Setting Cache-Control for Static Assets

location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Example: Using expires with relative time

location ~* \.(css|js)$ {
    expires 1d;
    add_header Cache-Control "public";
}

9. Serving Files with Try Files

Directive	Values	Description
try_files	`location` `...` `=` `404`	Checks for files in order and serves the first one found

Example: Basic try_files usage

location / {
    try_files $uri $uri/ /index.html;
}

Example: Fallback to 404

location / {
    try_files $uri $uri/ =404;
}

Note: The =404 part is optional and can be replaced with a custom error page or another location block.

10. Handling Missing Files

Directive	Description	Default	Notes
error_page	Defines the page to serve when an error occurs (e.g., 404, 500)	None	Can specify multiple error codes and pages
try_files	Checks for files in order and serves the first one found, or returns a 404	None	Useful for fallbacks and static file serving

Example: 404 Error Page

error_page 404 /404.html;
location = /404.html {
    internal;
}

Example: Fallback to Index

location / {
    try_files $uri $uri/ /index.html =404;
}

Note: The try_files directive is particularly useful for single-page applications or when serving static content where a fallback index.html is needed.

11. Serving Pre-compressed Files

Directive	Description	Values	Notes
gzip_static	Enables serving of pre-compressed files	`on` \| `off`	Must be used with `gzip on`
gzip_static	Controls whether to serve .gz files	`on` \| `off` \| `always`	`always` serves .gz files even if client doesn't support it

Example: Serving pre-compressed files

server {
    listen 80;
    root /var/www/html;

    location / {
        gzip_static on;
        gzip on;
        gzip_types text/plain application/javascript text/css;
    }
}

Note: Pre-compressed files must be named with .gz extension (e.g., style.css.gz) and placed alongside the original files.

12. Implementing Byte-Range Requests

Directive	Description	Default
http_range	Enables or disables byte-range requests for static content	`on`
sendfile_max_range	Maximum size of a single sendfile() call	`1024m`

Example: Enabling Range Requests

location /static/ {
    root /var/www;
    http_range on;
}

Note: Byte-range requests allow clients to request specific parts of a file, useful for resumable downloads and video streaming.

Warning: Enabling http_range can increase memory usage for large files.