Nginx as a Reverse Proxy for Gunicorn

The Production Architecture

Let's start with a visual of our target architecture.

This separation of concerns is fundamental:

• Nginx is the public-facing entry point. It excels at handling thousands of connections, terminating SSL, and serving static files from disk at high speed.
• Gunicorn is the application server. Its job is to manage Python worker processes and translate HTTP requests from Nginx into a format the Django application can understand (WSGI). It's not designed to be exposed directly to the internet.

Let's get our hands dirty and build this.

A Practical Walkthrough with Docker

For this lesson, we will follow a comprehensive video tutorial that uses Docker to set up the environment. This is an excellent modern approach as it allows us to create isolated, reproducible environments for our application (Django/Gunicorn) and our reverse proxy (Nginx).

The video uses Django, which aligns perfectly with your experience. We will proceed step-by-step, focusing first on getting the Django application running with Gunicorn, and then placing Nginx in front of it.

Part 1: Running the Django Application with Gunicorn

Before we can put Nginx in front of our application, we need the application to be running under the control of a proper application server, not Django's built-in development server.

Your experience with manage.py runserver is for development. In production, we use a WSGI server like Gunicorn. The process involves:

1. Installing Gunicorn into our project's environment.
2. Running Gunicorn and telling it where our Django project's WSGI application object is located (usually in myproject/wsgi.py).
3. Binding Gunicorn to a network address and port (e.g., 127.0.0.1:8000) so that other processes on the same machine (like Nginx) can connect to it.
4. Running collectstatic to gather all static files (from your apps and the Django admin) into a single directory.

The next segment of the video walks through this setup within a Docker container.

Part 2: Configuring Nginx as a Reverse Proxy

Now that Gunicorn is serving our Django application on port 8000, we'll introduce Nginx as the front door. Nginx will listen on the standard web port (80), and its primary job will be to proxy pass requests to Gunicorn.

The core of this configuration lies in a server block in an Nginx configuration file. The key directive is proxy_pass.

server {
    listen 80;
    server_name your_domain.com;

    location / {



        # This is the magic part.
        # It tells Nginx to forward any request for the root path '/'
        # to the Gunicorn server listening on localhost port 8000.
        proxy_pass http://127.0.0.1:8000;




        # These headers are important to pass along original request info
        # to the Django application.
        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;
    }
}

Let's see this in action. The next part of the video implements this exact logic.

For a text-based alternative that explains these directives clearly, the following article is an excellent reference.

Part 3: Offloading Static Files to Nginx

Our reverse proxy is working, but there's one major optimization left. Right now, requests for static files (like CSS and JavaScript) are also going through the full proxy chain: Nginx -> Gunicorn -> Django. This is inefficient.

A much better approach is to configure Nginx to handle these requests directly. Since we ran collectstatic, all our static files are in one known directory. We can tell Nginx: "If a request comes in for a URL starting with /static/, don't bother Gunicorn. Just find the corresponding file in the static directory on the filesystem and serve it yourself."

This is done with a second location block in our Nginx configuration.

location /static/ {



    # 'alias' tells Nginx the path on the file system that
    # corresponds to this URL path.
    alias /path/to/your/project/staticfiles/;
}

Let's see the final piece of the puzzle fall into place.

Conclusion

Congratulations! You have now configured the cornerstone of a modern web application deployment. By placing Nginx in front of a Gunicorn-managed Django application, you have created a robust, scalable, and performant architecture.

Key Takeaways:

• A production setup consists of a web server (Nginx) acting as a reverse proxy for an application server (Gunicorn).
• The key Nginx directive is proxy_pass, which forwards requests to the application server listening on a TCP port or a Unix socket.
• It's crucial to pass headers like Host and X-Forwarded-For so the backend application is aware of the original client's request details.
• A major performance gain comes from configuring Nginx with a location /static/ block to serve static assets directly from the filesystem, bypassing the Python application entirely.
• This architecture lets each component do what it does best: Nginx handles raw network traffic and static files, while Gunicorn and Django handle dynamic application logic.

Preview of the Next Lesson:
So far, every request we've handled has been stateless. The server responds to a request without any memory of previous interactions with that client. But most real applications need to maintain state—knowing who is logged in, what's in their shopping cart, etc. In our next lesson, we will dive into how this is achieved by exploring how cookies and sessions work at the HTTP protocol level to maintain state.