How to Configure Nginx as a Reverse Proxy for Spring Boot (With SSL) – 2026 Guide

Configure Nginx as a Reverse Proxy for Spring Boot

You have built your Spring Boot JAR. It runs perfectly on localhost:8080. You deploy it to your Linux server, and now you need to expose it to the world on port 80 (HTTP) or 443 (HTTPS).

This is where Nginx comes in. But if you have ever stared at a black terminal screen debugging a “502 Bad Gateway” error because you missed a semicolon or added a trailing slash where you shouldn’t have, you know the pain.

Configuring a reverse proxy seems simple until you need to handle real-world issues like SSL termination, Client IP forwarding, and WebSockets. A bad config doesn’t just break your site; it can leave security holes wide open.

1. The Architecture: Why Nginx?

Why not just run Spring Boot on port 80? Technically, you can. But in production, this is a bad idea.

Nginx acts as a “bodyguard” for your application. It handles the heavy lifting of encryption (SSL/TLS), compresses static files (Gzip), and protects your app from slow connections. Your Spring Boot app can then focus purely on business logic.

2. The “Bare Minimum” Configuration

At its core, a reverse proxy just takes traffic from the internet and passes it to localhost:8080. Here is the simplest working block:

server { listen 80; server_name example.com;

location / {
    proxy_pass http://localhost:8080;
}

}

⚠️ Warning: This config is too simple. It hides the client’s IP address from your Java app (Spring will think every request is coming from 127.0.0.1) and it will crash if a user uploads a file larger than 1MB.

3. The “Production-Ready” Block

To run a real Spring Boot application, you need to pass specific headers so that request.getRemoteAddr() in Java works correctly. You also need to handle timeouts for long-running processes.

server { listen 80; server_name example.com;

location / {
    # 1. Forward the request to Spring Boot
    proxy_pass http://localhost:8080;

    # 2. The "Truth" Headers (Crucial for Java)
    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;

    # 3. Handle Large Uploads (Fixes 413 Errors)
    client_max_body_size 10M;

    # 4. Increase Timeouts (Fixes 504 Gateway Timeouts)
    proxy_connect_timeout 60s;
    proxy_read_timeout 60s;
}

}

The “Trailing Slash” Trap

Notice that we wrote proxy_pass http://localhost:8080; without a slash at the end.

• With Slash (…:8080/): Nginx strips the path. Requesting /api/users becomes /users in Spring Boot.
• Without Slash (…:8080): Nginx passes the full path. Requesting /api/users stays /api/users.

99% of the time, you want NO slash.

4. Adding SSL (HTTPS)

In 2026, you cannot run a site on HTTP. Browsers will block it. You need an SSL certificate (usually from Let’s Encrypt).

An SSL configuration requires a second server block listening on port 443, with paths to your certificate files.

server { listen 443 ssl http2; server_name example.com;

# SSL Certs (Generated by Certbot)
ssl_certificate /etc/letsencrypt/live/[example.com/fullchain.pem](https://example.com/fullchain.pem);
ssl_certificate_key /etc/letsencrypt/live/[example.com/privkey.pem](https://example.com/privkey.pem);

# Security Headers
add_header Strict-Transport-Security "max-age=31536000" always;

location / {
    proxy_pass http://localhost:8080;
    # ... (include headers from above)
}

}

5. Common Nginx Errors & Fixes

Frequently Asked Questions