How to Use Nginx with Spring Boot: Setup and Configuration

To use nginx with a Spring Boot application, configure Nginx as a reverse proxy that forwards client requests to the Spring Boot server running on a specific port. This setup improves security, load balancing, and allows serving static content efficiently.

Syntax

The basic syntax involves configuring Nginx to listen on a port (usually 80 or 443) and proxy requests to the Spring Boot app running on another port (commonly 8080). Key parts include server, location, and proxy_pass.

• server: Defines the Nginx server block.
• listen: Port Nginx listens on.
• location /: URL path to match.
• proxy_pass: URL of the Spring Boot backend.

nginx

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:8080;
        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;
    }
}

Example

This example shows a complete Nginx configuration to reverse proxy requests to a Spring Boot app running locally on port 8080. It forwards headers correctly to preserve client info and supports HTTP traffic on port 80.

nginx

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
    }
}

Output

Nginx listens on port 80 and forwards all requests to Spring Boot on port 8080, preserving client headers.

Common Pitfalls

• Not forwarding headers like Host and X-Forwarded-For can cause issues with client IP detection and URL generation.
• Forgetting to open the Spring Boot port (e.g., 8080) in firewall settings blocks traffic.
• Running Spring Boot on the same port as Nginx causes conflicts; they must use different ports.
• Not configuring Spring Boot to recognize forwarded headers can cause incorrect redirects or URL building.

nginx

Wrong way:
server {
    listen 80;
    server_name example.com;

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

Right way:
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8080;
        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;
    }
}

Quick Reference

Remember these tips when using Nginx with Spring Boot:

• Run Spring Boot on a port different from Nginx (e.g., 8080 vs 80).
• Use proxy_pass to forward requests.
• Set headers to preserve client info.
• Configure Spring Boot to handle forwarded headers by enabling server.forward-headers-strategy=framework in application.properties.
• Reload Nginx after changes with sudo nginx -s reload.

Key Takeaways

Configure Nginx as a reverse proxy forwarding requests to Spring Boot on a different port.

Always forward headers like Host and X-Forwarded-For to preserve client information.

Ensure Spring Boot is configured to recognize forwarded headers for correct URL handling.

Avoid port conflicts by running Nginx and Spring Boot on separate ports.

Reload Nginx after configuration changes to apply updates.