Configuring Nginx on Laravel Forge: Architecture and Tuning

A common misconception is that Laravel Forge maintains immutable Nginx configurations that break whenever you modify them directly or deploy site updates. In reality, Forge generates clean, decoupled server blocks that you can customize via the dashboard or directly on disk without losing automation. A Laravel Forge Nginx configuration manages traffic routing from client connections down to PHP-FPM UNIX domain sockets, handling SSL termination, static file caching, HTTP/2 or HTTP/3 multiplexing, and rewrite rules for single-page applications or standard Laravel monoliths.

When you spin up a server on Forge, the provisioner establishes a baseline configuration located at /etc/nginx/sites-available/your-domain.com, linked directly into /etc/nginx/sites-enabled/. Understanding how Forge constructs these server blocks allows you to tune worker processes, eliminate socket starvation under high concurrent traffic, resolve stubborn CORS headers, and prevent gateway timeouts on long-running exports.

Anatomy of the Default Laravel Forge Nginx Server Block

The Laravel Forge Nginx configuration is a standard Nginx server block that routes incoming HTTP and HTTPS traffic through PHP-FPM via local UNIX sockets. Forge generates this file automatically when you provision a site, defining root directories, index priorities, character encoding, access logs, and upstream fastcgi parameters.

Understanding each block in this configuration prevents deployment surprises. Below is an authentic representation of the baseline file Forge generates on an Ubuntu provisioned node:

# Default Laravel Forge Site Configuration
# Path: /etc/nginx/sites-available/example.com

server {
 listen 80;
 listen [:]:80;
 server_name example.com www.example.com;
 root /home/forge/example.com/public;

 # Forge security rules and base headers
 add_header X-Frame-Options "SAMEORIGIN";
 add_header X-Content-Type-Options "nosniff";

 index index.html index.htm index.php;

 charset utf-8;

 # Forge standard rule inclusions
 include forge-conf/example.com/before/*;

 location / {
 try_files $uri $uri/ /index.php?$query_string;
 }

 location = /favicon.ico { access_log off; log_not_found off; }
 location = /robots.txt { access_log off; log_not_found off; }

 access_log off;
 error_log /var/log/nginx/example.com-error.log error;

 error_page 404 /index.php;

 location ~ \.php$ {
 fastcgi_split_path_info ^(.+\.php)(/.+)$;
 # Direct socket connection to the PHP-FPM daemon
 fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
 fastcgi_index index.php;
 include fastcgi_params;
 fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
 fastcgi_param DOCUMENT_ROOT $realpath_root;
 }

 location ~ /\.(?well-known).* {
 deny all;
 }

 include forge-conf/example.com/after/*;
}

The critical directives to notice are the include forge-conf/example.com/before/* and include forge-conf/example.com/after/* statements. These directives allow granular configuration layering without overriding the primary block directly, which is central to keeping Forge automation working alongside manual adjustments.

How Forge Manages Configuration Persistence and Custom Includes

A critical point of confusion for engineers working with Forge is file persistence. Modifying files directly in /etc/nginx/sites-available/ is dangerous because triggering an SSL certificate renewal or changing site details via the Forge dashboard completely regenerates the main server block. Any edits made on disk to that specific file get wiped out.

The Forge Configuration Lifecycle

Forge provides two distinct ways to modify the configuration safely:

1. The Forge UI Editor: In the site panel, navigate to Configuration → Edit Nginx Configuration. This form loads the authoritative template stored in Forge’s database. Saving here overwrites /etc/nginx/sites-available/example.com and tests the configuration syntax via nginx -t before reloading the system daemon.
2. Include Directories: On disk, Forge creates the /etc/nginx/forge-conf/example.com/ hierarchy. The server block includes any file matching the pattern inside before/ and after/. Files placed in these folders survive dashboard updates completely untouched.

Use the UI editor for server-wide modifications such as listen ports or root paths. Use disk-level includes in forge-conf/ for automated deployments via configuration management tools like Ansible, Puppet, or custom shell hooks.

Tuning PHP-FPM FastCGI Buffers for Complex Payloads

A common error encountered by Laravel applications handling large JSON payloads or multi-column reporting exports is upstream sent too big header while reading response header from upstream. This happens when the response headers emitted by Laravel (such as extensive session cookies, debug data, or authentication tokens) exceed the FastCGI buffer allocations configured by default.

By default, Nginx allocates small memory pages to buffer responses from PHP-FPM. When building interactive user interfaces, such as custom Livewire schema forms that carry larger state payloads in HTTP headers, default buffers can overflow quickly.

# Insert into the location ~ \.php$ block via Forge UI
location ~ \.php$ {
 fastcgi_split_path_info ^(.+\.php)(/.+)$;
 fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
 fastcgi_index index.php;
 include fastcgi_params;
 
 # Extended buffer configuration
 fastcgi_buffer_size 32k;
 fastcgi_buffers 16 16k;
 fastcgi_busy_buffers_size 64k;
 fastcgi_temp_file_write_size 64k;
 
 # Mitigate slow downstream processing
 fastcgi_read_timeout 180s;
 fastcgi_send_timeout 180s;
 
 fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
 fastcgi_param DOCUMENT_ROOT $realpath_root;
}

Adjusting these buffers prevents Nginx from buffering FastCGI responses to temporary disk files, keeping high-throughput operations purely in RAM and reducing disk I/O wait times under heavy concurrency.

Configuring Client Upload Limits and Avoiding HTTP 413

Out of the box, Nginx enforces an exceptionally conservative limit on incoming HTTP request bodies: exactly 1 megabyte. If a user uploads a profile picture, PDF invoice, or media file exceeding this threshold, Nginx terminates the connection immediately with an HTTP 413 Request Entity Too Large response before the request ever reaches the Laravel routing layer.

Applying the Client Max Body Size

To support larger file uploads, adjust the client_max_body_size directive within the site’s server block:

server {
 listen 443 ssl http2;
 server_name example.com;
 root /home/forge/example.com/public;

 # Allow request bodies up to 64 Megabytes
 client_max_body_size 64M;
 
 # Allocate sufficient memory for request headers
 client_header_buffer_size 4k;
 large_client_header_buffers 4 16k;

 # Remaining Forge configuration..
}

Keep in mind that modifying Nginx alone is only half the equation. You must also synchronize this value with your active PHP runtime settings in /etc/php/8.3/fpm/php.ini:

; Synchronize with client_max_body_size
upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M

If post_max_size is smaller than client_max_body_size, PHP silently drops the POST body, causing form submissions to arrive completely empty without raising a traditional application exception.

Handling Single-Page Applications and Sub-Directory Routings

When combining a standard Laravel API backend with a decoupled single-page application (SPA) like a Vue or React frontend, standard routing rules must change. The default Forge directive, try_files $uri $uri/ /index.php?$query_string;, directs all unmatched requests to Laravel’s entry point.

Serving a Client-Side App from a Subfolder

Consider an architecture where Laravel powers an API, but an administrative dashboard lives in a sub-path such as /admin/ containing compiled static assets:

# Admin SPA Client Sub-directory
location /admin {
 alias /home/forge/example.com/public/admin/dist;
 try_files $uri $uri/ /admin/index.html;
}

# Main Laravel Application Fallback
location / {
 try_files $uri $uri/ /index.php?$query_string;
}

# API requests explicitly handed to PHP
location /api {
 try_files $uri $uri/ /index.php?$query_string;
}

Notice the use of alias instead of root. When using a location block with a path prefix like /admin, alias swaps the prefix for the defined filesystem path. Using root would append /admin to the specified directory, leading to broken 404 Not Found path resolutions.

Aggressive Static Asset Caching and Gzip Optimization

Serving static files through Nginx without explicit expiration directives forces clients and CDNs to make conditional GET requests on every asset. Adding explicit Cache-Control headers offloads significant bandwidth and CPU cycles from the server.

You can optimize static delivery by placing an asset-handling block directly above the primary location / handler:

# High-efficiency static caching
location ~* \.(jpg|jpeg|gif|png|webp|svg|ico|css|js|woff|woff2|ttf)$ {
 expires 365d;
 add_header Cache-Control "public, no-transform, immutable";
 access_log off;
 log_not_found off;
 
 # Enable direct file descriptor transfer bypass
 sendfile on;
 tcp_nopush on;
 tcp_nodelay on;
}

Additionally, check your global compression settings inside /etc/nginx/nginx.conf. Forge provisions Nginx with basic gzip enabled, but you can expand the supported MIME types to cover modern asset variants:

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 5;
gzip_min_length 256;
gzip_types
 application/atom+xml
 application/javascript
 application/json
 application/ld+json
 application/manifest+json
 application/rss+xml
 application/vnd.geo+json
 application/vnd.ms-fontobject
 application/x-font-ttf
 application/x-web-app-manifest+json
 image/svg+xml
 text/cache-manifest
 text/css
 text/javascript
 text/plain
 text/xml;

Compression level 5 strikes the optimal balance between CPU utilization and byte savings. Higher levels like 8 or 9 consume non-linear CPU resources for negligible reductions in file size.

Hardening Security Headers and Blocking Sensitive Files

While Forge applies basic headers such as X-Frame-Options and X-Content-Type-Options, an enterprise deployment demands a stricter security posture. Laravel applications frequently bundle sensitive metadata files, SQLite databases, package manifests, or environment files that must never be accessible over public HTTP.

Strict Transport Security and Content Isolation

Inject the following directives into your server block to establish modern security boundaries:

# Enforce HTTPS via HSTS with subdomains and preload eligibility
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

# Prevent MIME-type sniffing
add_header X-Content-Type-Options "nosniff" always;

# Prevent embedding within unauthorized iframes
add_header X-Frame-Options "DENY" always;

# Control cross-origin resource leakage
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# Block Git repositories, environment configurations, and lock files
location ~ /\.(?well-known).* {
 deny all;
 return 404;
}

location ~* (composer\.json|composer\.lock|package\.json|package-lock\.json|\.env) {
 deny all;
 return 404;
}

Returning a 404 Not Found rather than a 403 Forbidden when blocking sensitive directories prevents automated vulnerability scanners from confirming whether specific configuration files exist on the server.

Diagnosing Socket Bottlenecks and Upstream Errors

When incoming traffic spikes, Laravel applications on Forge often encounter 502 Bad Gateway or 504 Gateway Timeout errors. These errors indicate that the communication bridge between Nginx and PHP-FPM has failed.

Identifying the Root Cause

When debugging application issues, use the shell to inspect logs and check active states. For runtime application debugging, utilities like interactive Tinker CLI execution help isolate database or model delays from web layer stalls.

The two most common failure modes in Nginx are socket exhaustion and process pool limits:

• Socket Backlog Overflow: If PHP-FPM cannot process incoming requests quickly enough, the UNIX socket backlog fills up. Nginx immediately reports connect() to unix:/var/run/php/php8.3-fpm.sock failed (11: Resource temporarily unavailable).
• FPM Max Children Starvation: If every PHP worker child is occupied by long-running SQL queries or third-party API calls, subsequent requests wait in line until the connection times out.

Inspect connection behavior using standard Linux performance tools:

# Check the active queue depth on the PHP-FPM UNIX domain socket
ss -l -x | grep php8.3-fpm.sock

# Review real-time Nginx error traces
tail -n 50 -f /var/log/nginx/example.com-error.log

If the queue fills up repeatedly, tune /etc/php/8.3/fpm/pool.d/www.conf to increase pm.max_children and ensure the system somaxconn value matches the expected load.

CORS Header Configuration at the Web Server Layer

While Laravel provides packages like Fruitcake CORS or built-in middleware to handle Cross-Origin Resource Sharing, handling preflight OPTIONS requests in PHP adds unnecessary overhead. Every preflight request has to boot the Laravel framework kernel, parse providers, and run middleware pipelines before returning a set of headers.

Handling preflight requests directly in Nginx allows the server to resolve them in sub-millisecond times without touching PHP-FPM:

location /api/ {
 # Intercept OPTIONS preflight immediately
 if ($request_method = 'OPTIONS') {
 add_header 'Access-Control-Allow-Origin' 'https://app.example.com' always;
 add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, PATCH, DELETE, OPTIONS' always;
 add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Accept, X-Requested-With' always;
 add_header 'Access-Control-Max-Age' 86400;
 add_header 'Content-Length' 0;
 add_header 'Content-Type' 'text/plain; charset=utf-8';
 return 204;
 }

 try_files $uri $uri/ /index.php?$query_string;
}

This configuration immediately answers preflight requests with an HTTP 204 No Content, caching the authorization for 24 hours (86,400 seconds) in the client’s browser cache.

Load Balancing Multiple App Nodes Behind a Forge Load Balancer

As traffic scales beyond what a single server can process, you can configure Laravel Forge to provision a dedicated Load Balancer node running Nginx. This node distributes requests across an upstream pool of application workers.

Under the hood, Forge configures an upstream block that uses round-robin distribution by default. You can adjust this configuration to use the least connections algorithm, which balances work more effectively when request processing times vary significantly:

# Managed Upstream Cluster in Forge Load Balancer
upstream backend_nodes {
 least_conn;
 
 # App Server 01
 server 10.0.0.10:80 max_fails=3 fail_timeout=10s;
 # App Server 02
 server 10.0.0.11:80 max_fails=3 fail_timeout=10s;
 
 # Keepalive connections to reduce TCP handshake overhead
 keepalive 32;
}

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

 location / {
 proxy_pass http://backend_nodes;
 proxy_http_version 1.1;
 
 proxy_set_header Connection "";
 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;
 
 # Buffer configurations for proxying
 proxy_buffers 16 16k;
 proxy_buffer_size 16k;
 }
}

The keepalive 32; directive maintains open TCP connections between the load balancer and downstream application nodes, cutting out recurring handshake overhead on high-volume routes.

Comparing Infrastructure Cost Models for Forge Deployments

Managing Nginx configurations and production servers on Laravel Forge involves distinct cost trade-offs depending on whether you manage configurations internally, hire contract specialists, or use retained platform engineering support.

For small-scale applications, running Forge directly on an entry-level virtual server (such as an 8GB RAM, 4 vCPU instance costing around $48 per month on DigitalOcean, Linode, or Hetzner) delivers strong performance at minimal operational expense. However, when an application hits hundreds of requests per second, investing in specialized Nginx and PHP-FPM performance tuning usually saves thousands of dollars in unnecessary infrastructure upgrades.

Related Laravel Core Infrastructure Guides

Mastering web server internals is an essential part of maintaining reliable web applications. If you are refining other areas of your deployment pipeline, configuration mechanics, or framework patterns, explore our comprehensive collection of deep-dive material.

Explore our complete Laravel — Basics directory for more guides.

A Laravel Forge Nginx configuration is not a fragile, closed system. It is a structured, production-ready environment that you can customize to fit your application’s exact needs. By understanding the relationship between the web UI and disk-level configuration files, setting appropriate buffer limits, and using include files for persistent changes, you can avoid configuration overwrites during deployments.

Profile your upstream socket connections, align client payload thresholds across both Nginx and PHP runtimes, and terminate preflight requests directly at the web server layer. This approach maximizes application performance, stabilizes response times, and keeps your server infrastructure running efficiently as traffic grows.