Nginx Part 2

 

How to Configure Nginx to Serve Uploaded Files (Images & PDFs) in Production

Modern web applications often allow users to upload files such as images, PDFs, and documents. While uploading files through the backend is common, serving those files efficiently in production requires proper server configuration.

A common and highly recommended approach is to let Nginx serve uploaded files directly, instead of routing those requests through the backend server. This improves performance, reduces load on the API server, and ensures faster content delivery.

In this blog, we will walk through a production-ready Nginx configuration used to serve uploaded files securely and efficiently.

---

Why Use Nginx for Serving Uploaded Files?

Many developers initially serve uploaded files through their backend framework (Node.js, Django, Laravel, etc.). While this works, it is not ideal for production environments.

When a backend server handles file downloads, it consumes CPU and memory resources that should ideally be used for business logic and API operations.

Nginx, on the other hand, is optimized for serving static content. It can handle thousands of file requests efficiently with minimal resource usage.

Using Nginx for static files provides several benefits:

• Faster file delivery

• Reduced backend workload

• Better caching support

• Improved scalability

• More efficient resource utilization

---

Example Nginx Configuration for File Uploads

Below is a typical Nginx configuration used to serve uploaded images and PDF files.

location ^~ /uploads/ {
    alias /var/www/yourfolder/backend/uploads/;
    autoindex off;
    access_log off;

    types {
        image/jpeg  jpg jpeg;
        image/png   png;
        application/pdf pdf;
    }

    default_type application/octet-stream;

    add_header Cache-Control "public, max-age=31536000, immutable";

    try_files $uri =404;
}

Let’s understand what each part of this configuration does and why it is important.

---

1. The Location Block

location ^~ /uploads/

This directive tells Nginx to handle any request that starts with /uploads/.

For example:

https://yourdomain.com/uploads/image.png

When a request like this arrives, Nginx immediately checks this block and processes the request using the rules defined inside it.

The ^~ modifier gives this block higher priority than other prefix-based location matches, ensuring that file requests are handled correctly.

---

2. Mapping URL Paths to Server Directories

alias /var/www/yourfolder/backend/uploads/;

The alias directive maps a public URL path to an actual directory on the server.

For example:

Public request:

/uploads/media/photo.png

Actual file location on server:

/var/www/.../uploads/media/photo.png

This means Nginx directly reads the file from the filesystem and sends it to the browser.

One important rule when using alias is that the path must end with a trailing slash. Without the trailing slash, file resolution may fail.

---

3. Disabling Directory Listing

autoindex off;

By default, if directory listing is enabled, users could potentially view all files inside the uploads directory simply by visiting the folder URL.

For example:

https://yourdomain.com/uploads/

If directory listing is enabled, users might see all uploaded files. Disabling it prevents this and improves security.

---

4. Disabling Access Logs for Static Files

access_log off;

Static file requests can generate a large number of log entries.

For example, every time a browser loads images or PDFs, a new log entry is created.

Disabling logs for static files helps:

• Reduce log file size

• Improve performance

• Keep logs focused on important requests like APIs

---

5. Defining MIME Types

types {
    image/jpeg  jpg jpeg;
    image/png   png;
    application/pdf pdf;
}

The types block tells Nginx what Content-Type header should be returned for specific file extensions.

For example:

File Extension	MIME Type Returned
.jpg	image/jpeg
.png	image/png
.pdf	application/pdf

This ensures browsers correctly display images and open PDF files properly.

---

6. Default MIME Type

default_type application/octet-stream;

If Nginx encounters a file extension that is not defined in the types block, it will use this default type.

application/octet-stream is a generic binary type that tells the browser the file is a downloadable resource.

This prevents browsers from misinterpreting unknown file formats.

---

7. Enabling Browser Caching

add_header Cache-Control "public, max-age=31536000, immutable";

Caching improves performance by allowing browsers to store static files locally.

Explanation:

• public means both browsers and proxies can cache the file

• max-age=31536000 means the file can be cached for one year

• immutable indicates the file will not change during its lifetime

This is ideal for uploaded files with unique names (for example, UUID-based filenames).

Caching significantly reduces server load and speeds up page loading.

---

8. Ensuring File Exists

try_files $uri =404;

This directive checks whether the requested file actually exists.

Behavior:

If the file exists, Nginx serves it directly.

If the file does not exist, Nginx returns a 404 Not Found response.

This prevents requests from accidentally falling through to other routing rules.

---

Important Rule for Single Page Applications (SPA)

If your frontend application is built using frameworks like React, Vue, or Angular, your server likely includes a fallback rule like this:

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

This rule ensures frontend routes work correctly.

However, the uploads configuration must appear before this rule, otherwise file requests might incorrectly return the frontend application HTML.

Correct order:

location ^~ /uploads/ { ... }

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

---

Final Request Flow

When a user requests a file:

https://yourdomain.com/uploads/image.png

The request flow looks like this:

User → Nginx → Uploads Folder → File Served

The backend server is not involved at all.

This makes the system faster, more scalable, and easier to maintain.

---

Final Thoughts

Handling file uploads in production is not just about writing upload logic in the backend. It also requires proper server configuration.

By allowing Nginx to serve uploaded files directly, you can:

• Improve performance

• Reduce backend load

• Enable efficient caching

• Provide a more scalable architecture

A well-configured Nginx setup ensures that uploaded files are delivered quickly, securely, and reliably.

Understanding these configurations is an important step toward building production-ready web applications.