Nginx Reverse Proxy Load Balancer Cursor Rules Template

Overview

Cursor rules configuration for nginx-reverse-proxy-load-balancer-template covers building a secure, scalable nginx-based front door for a backend API stack. It targets a typical setup where Nginx terminates TLS, proxies requests to a pool of backend services, and applies load balancing, health checks, and security best practices. Direct answer: paste the .cursorrules block below into your project root to guide Cursor AI in generating and validating stack-specific nginx configs.

When to Use These Cursor Rules

• Setting up a new nginx-based reverse proxy and load balancer in front of a backend API cluster.
• Automating config generation and validation with Cursor AI during CI/CD.
• Enforcing security defaults (TLS termination, HSTS, request limiting) across environments.
• Maintaining consistent upstream definitions and site-enabled server blocks.

Copyable .cursorrules Configuration

# Cursor Rules for nginx-reverse-proxy-load-balancer
Framework Role & Context:
- Role: Cursor AI config assistant for nginx reverse proxy & upstream load balancer
- Context: Stack includes Nginx in front of backend API services behind TLS; Cursor AI to generate, validate, and harden configs

Code Style and Style Guides:
- Indent with 2 spaces
- Use upstream blocks and include them in server blocks
- Do not embed secrets or credentials; use environment or secret manager

Architecture & Directory Rules:
- Project structure rooted at repo
- Config files: config/nginx/nginx.conf, config/nginx/upstreams.conf, config/nginx/sites-enabled/*.conf
- Lockfiles and deployment scripts live under scripts/ and .gitignore excludes secrets

Authentication & Security Rules:
- TLS termination at edge; redirect HTTP to HTTPS
- Enable HSTS, disable server_tokens, set secure ciphers and protocol versions
- Enforce body size limits, rate limiting, and IP-based access controls

Database and ORM patterns:
- Nginx does not connect to a database; backend apps handle DB interactions
- Do not proxy raw DB ports; use application layer to access DBs

Testing & Linting Workflows:
- Validate config with nginx -t
- Run curl health checks for upstreams
- CI should run nginx config tests on merge, plus integration tests against /health endpoints
- Lint upstream and site configs with a linter if available

Prohibited Actions and Anti-patterns:
- Do not expose admin interfaces on public ports
- Do not embed credentials in nginx.conf or upstreams.conf
- Do not disable TLS or security headers without a compensating control

# Example upstream and server blocks (illustrative; adapt to your environment)
upstream api_backends {
  least_conn;
  server 10.0.1.10:3000;
  server 10.0.1.11:3000;
}

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

  ssl_certificate /etc/ssl/certs/example.crt;
  ssl_certificate_key /etc/ssl/private/example.key;

  location / {
    proxy_pass http://api_backends;
    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_http_version 1.1;
    proxy_set_header Connection "";
  }

  error_page 502 503 504 /50x.html;
  location = /50x.html {
    root /usr/share/nginx/html;
  }
}

Recommended Project Structure

/
├── backend/
│   └── src/
├── config/
│   └── nginx/
│       ├─ nginx.conf
│       ├─ upstreams.conf
│       └─ sites-enabled/
│           └─ app.conf
├── cursorrules/
│   └─ nginx-reverse-proxy-load-balancer-cursor-rules/
│       └─ rules.cursorrules
├── scripts/
└── tests/

Core Engineering Principles

• Configuration as code: idempotent, version-controlled, and auditable.
• Security by default: TLS, HSTS, strict headers, and minimal exposed surface.
• Clear separation of concerns: proxy layer, upstreams, and application logic.
• Observability: tools for health checks, logging, and metrics in nginx and backends.
• Deterministic builds: deterministic upstream order and predictable retries.

Code Construction Rules

• Upstreams must be defined in config/nginx/upstreams.conf and included where needed.
• Server blocks must reference upstreams by name only; avoid hard-coded IPs outside upstreams.conf when possible.
• TLS termination and certificate management must be decoupled from code, using env or secret management.
• Proxies should forward essential headers and preserve client IPs.
• Health checks should be implemented at the application layer; nginx should not perform application logic health checks.

Security and Production Rules

• Redirect all HTTP to HTTPS; enable HSTS with a reasonable max-age.
• Disable server_tokens; use secure ciphers and TLS 1.2+ (prefer TLS 1.3).
• Limit request sizes and rate-limit per IP; apply WAF rules if available.
• Use TLS certificates from a trusted CA and automate renewal.

Testing Checklist

• lint nginx configs; run nginx -t
• curl -I https://api.example.com/health to verify responses
• simulate upstream failure and verify 502/503 fallbacks
• end-to-end tests with CI to ensure TLS and routing work

Common Mistakes to Avoid

• Overly permissive upstream blocks or wildcard allow rules
• Disabling TLS or security headers in production
• Hardcoding secrets in config files

FAQ

What is the purpose of this Cursor Rules Template for nginx?

This Cursor Rules Template provides a copyable .cursorrules block and stack-specific guidance to help Cursor AI generate, validate, and maintain nginx reverse proxy and load balancer configurations for a secure API gateway.

Can I use this with multiple backend services?

Yes. Define multiple upstream servers in upstreams.conf and reference them in the server block. Cursor AI helps ensure consistent health checks and failover behavior across services.

Where should I place the .cursorrules file?

Place it in the project root as rules.cursorrules or in a path used by your CI pipeline. It guides AI-assisted config generation and validation.

Does this template enforce TLS at the edge?

Yes. The template emphasizes TLS termination at Nginx, TLS 1.2+ (prefer 1.3/1.4 where available), and HTTP-to-HTTPS redirects as a default security posture.

What if I need gRPC or WebSocket support?

The base template focuses on HTTP. To support gRPC or WebSocket, adjust proxy settings (e.g., upgrade headers, HTTP/1.1) and include stack-specific rules; Cursor AI can assist with these adaptations.