Laravel reverb nginx

Overview of Laravel Reverb and Nginx Integration

Laravel Reverb typically runs as a separate service on a non-web-facing port (e.g., 8080) on the server. Nginx acts as a reverse proxy to forward WebSocket and API traffic to the Reverb server. This setup enhances security by not exposing the WebSocket server directly and also allows Nginx to handle SSL termination and load balancing.

The most common Nginx setup for Laravel Reverb involves configuring proxying for specific paths where Reverb listens and serves WebSocket connections, generally `/app` for WebSocket connections and `/apps` for API requests.

Nginx Configuration for Laravel Reverb

In the Nginx configuration file for the Laravel application, the following block is typically added to the server block:

location /app {
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header Scheme $scheme;
    proxy_set_header SERVER_PORT $server_port;
    proxy_set_header REMOTE_ADDR $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";

    proxy_pass http://0.0.0.0:8080;
}

This configuration tells Nginx to proxy WebSocket requests arriving at `/app` to the Reverb server running on port 8080. The headers set ensure proper handling of the WebSocket upgrade request and forward client IP and protocol details correctly. It is crucial to keep the `/app` path unchanged as it is the designated endpoint for WebSocket connections in Reverb.

If the Laravel Reverb server runs on a local IP like `127.0.0.1`, the `proxy_pass` directive should match that:

proxy_pass http://127.0.0.1:8080;

To handle SSL termination, Nginx listens on port 443 with SSL enabled, while it communicates with the Reverb service over an unencrypted internal connection on port 8080.

Handling SSL and HTTPS with Laravel Reverb and Nginx

For applications using HTTPS, additional configuration steps are necessary. A subdomain (e.g., `ws.yourdomain.com`) may be created for the WebSocket server, pointing to the main domain via DNS CNAME. The SSL certificate should cover both the main domain and the WebSocket subdomain to enable secure SSL communication.

In the Nginx configuration, the server block listens on port 443 SSL and can proxy WebSocket requests as follows:

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location /app {
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header Scheme $scheme;
        proxy_set_header SERVER_PORT $server_port;
        proxy_set_header REMOTE_ADDR $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;

        proxy_pass http://127.0.0.1:8080;
    }
}

In this setup, Nginx terminates the SSL connection and then forwards the traffic to Reverb over HTTP. The WebSocket URL accessed by clients will typically be `wss://yourdomain.com/app/{REVERB_APP_KEY}`.

Laravel Environment (.env) Configuration for Reverb

The `.env` file of the Laravel application must be configured with the appropriate environment variables to enable Reverb broadcasting properly:

REVERB_APP_ID=your-app-id
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST=yourdomain.com
REVERB_PORT=443
REVERB_SCHEME=https
REVERB_SERVER_HOST=127.0.0.1
REVERB_SERVER_PORT=8080
BROADCAST_CONNECTION=reverb

# VITE variables for frontend if using Vite
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

- `REVERB_HOST` should match your application domain without protocol prefix.
- `REVERB_PORT` is commonly 443 for HTTPS.
- `REVERB_SERVER_HOST` and `REVERB_SERVER_PORT` refer to where Reverb listens locally.
- The broadcast connection should be set to use Reverb.

These variables enable Laravel Echo or equivalent front-end libraries to connect securely to the Reverb server.

Common Issues and Solutions

1. Server Crashing after Inactivity

A known issue exists where the Reverb server crashes if there is no activity for a certain time (e.g., 60 seconds). This is due to a bug in the application configuration retrieval process. Keeping the Reverb server busy or intercepting disconnects properly can mitigate this.

2. SSL Certificate and Domain Mismatch

When SSL is not properly configured, secure WebSocket connections (`wss://`) fail. Ensure the SSL certificate covers all domains/subdomains used by Reverb and that Nginx is correctly set up to handle SSL.

3. Nginx Proxy Timeout

WebSocket connections expect long-lived persistence; therefore, Nginx proxy timeouts should be set high enough (e.g., `proxy_read_timeout 300s;`) to avoid premature disconnections.

4. Misconfigured Environment Variables

Reverb requires specific `.env` variables set correctly. Missing or incorrect keys, hostnames, or ports will cause connection failures.

Scaling and Performance

Nginx limits on the number of open files and connections can restrict Reverb performance. To support thousands of concurrent connections, the following Nginx directives are recommended in `nginx.conf`:

worker_rlimit_nofile 10000;

events {
    worker_connections 10000;
    multi_accept on;
}

These settings increase the number of allowed simultaneous connections Nginx can handle, which benefits high-traffic real-time applications using Laravel Reverb.

Deployment Process with Laravel Reverb and Nginx

When deploying an application using Laravel Reverb with Nginx, consider the following steps:

1. Install Laravel Reverb package and broadcast configuration.
2. Configure Nginx to proxy WebSocket connections to Reverb.
3. Set the appropriate environment variables in `.env`.
4. Ensure SSL certificates are properly installed for HTTPS and WSS connections.
5. Start the Reverb server with the artisan command:

php artisan reverb:start

or with debug for troubleshooting:

php artisan reverb:start --debug

6. Ensure your front-end is correctly configured with the Reverb keys and host to establish WebSocket connections.
7. Monitor logs for any errors or disconnects.

Summary of Nginx Reverse Proxy Features for Laravel Reverb

- Proxy upgrade headers for WebSocket.
- Forward client host, scheme, port, and IP.
- Handle SSL termination at Nginx level.
- Increase proxy timeout settings for WebSocket longevity.
- Route `/app` path traffic to the internal Reverb server port.

Additional Notes

Laravel Forge users get automatic configuration for Reverb and SSL if set up correctly. If running multiple Laravel applications or Reverb services on the same server, adjust the ports accordingly.

Environment variables for front-end tooling like Vite must be kept in sync to avoid connection issues.

Removing subdomains like `ws.domain.com` from Nginx's `server_name` in some setups may resolve conflicts, as Reverb handles WebSocket connections on the main domain with proxy routes.

Using Laravel Reverb with SSL Example

In DNS, set up CNAME for the WebSocket subdomain:

- `ws.domain.com` CNAME to `domain.com`

In Nginx, remove `ws.domain.com` from `server_name` and enable SSL for `domain.com` only. Add the proxy for `/app` as above.

In `.env`:

REVERB_HOST=ws.domain.com
REVERB_PORT=443
REVERB_SCHEME=https

Then restart Reverb and build your front-end assets.

***