How do I set up Reverb's Forge integration for Laravel

Prerequisites

Before setting up Reverb's Forge integration, ensure you have the following ready:

- A Laravel application with Reverb installed.
- An active Laravel Forge account.
- A domain name with DNS management access.
- A version control repository (e.g., GitHub) containing your Laravel application code.

Local Development Setup

Begin by cloning your Laravel application repository locally. Navigate to the project directory, then install dependencies:

bash
git clone your-repo-url
cd your-project
composer install
npm install

If your application uses SQLite (or your chosen database), set up the database file accordingly:

bash
touch database/database.sqlite
php artisan migrate

Compile your assets:

bash
npm run dev

Start the Reverb server locally to verify that real-time features are functioning:

bash
php artisan reverb:start --debug

Test your application to ensure WebSocket connections and events work correctly before moving to production.

Server Provisioning on Laravel Forge

On your Laravel Forge dashboard:

1. Create a new server using your preferred cloud provider.
2. Choose "App Server" as the server type.
3. Select an appropriate server size based on your expected load.
4. Wait for the provisioning process to complete.

After provisioning, add a new site in the Forge dashboard:

1. Enter your domain or subdomain (e.g., `example.com`).
2. Link your GitHub repository and deploy your application.
3. Set up the deployment script to run necessary build and migration commands:

bash
   composer install --no-interaction --prefer-dist --optimize-autoloader
   npm install
   npm run build
   php artisan migrate --force
   

DNS Configuration

Configure DNS for your domain and WebSocket subdomain:

- For your main domain, create an A record pointing to your server's IP address.
- For the WebSocket server, create a CNAME record pointing a subdomain such as `ws.example.com` to your main domain.

This setup allows WebSocket connections to be routed correctly.

Enabling Laravel Reverb on Forge

Forge provides a toggle to enable Laravel Reverb easily:

1. In the Forge site dashboard, navigate to the Application tab.
2. Find the "Laravel Reverb" toggle and enable it.
3. Configure the public hostname, usually the WebSocket subdomain created earlier (e.g., `ws.example.com`).
4. Set the maximum number of concurrent connections as needed (default is typically 1000).
5. Start Laravel Reverb via Forge, which will handle daemon creation, WebSocket server configuration, environment variable updates, and process monitoring.

Forge will create a daemon running the Reverb server command, usually similar to:

bash
php artisan reverb:start --no-interaction --port=8080

Environment Configuration

Your `.env` file should include the necessary Reverb configuration variables:

BROADCAST_CONNECTION=reverb
REVERB_APP_ID=your-app-id
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST=ws.example.com
REVERB_PORT=8080
REVERB_SCHEME=https

Forge will update these variables automatically when you toggle Reverb on the Forge dashboard, but you can also set them manually.

Securing WebSocket Connections

To secure the WebSocket connections:

- Use SSL certificates provided by Forge (Let's Encrypt is integrated).
- Ensure your WebSocket subdomain has a SSL certificate issued.
- Use the `wss://` protocol in your client configuration to enforce secure WebSockets.

Client Configuration

In your frontend JavaScript, configure Laravel Echo or the WebSocket client with Reverb settings:

javascript
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: process.env.VITE_REVERB_APP_KEY,
    wsHost: process.env.VITE_REVERB_HOST,
    wsPort: process.env.VITE_REVERB_PORT,
    wssPort: process.env.VITE_REVERB_PORT,
    forceTLS: process.env.VITE_REVERB_SCHEME === 'https',
    enabledTransports: ['ws', 'wss']
});

Replace environment variables with appropriate values.

Deployment Script Adjustment

Ensure your Forge deployment script includes a command to restart the Reverb server after deployment:

bash
$FORGE_PHP artisan reverb:restart

This step ensures that the WebSocket server is always running the latest code after deployments.

Verifications and Troubleshooting

- Verify the daemon for Reverb is running in the Forge server dashboard.
- Ping your WebSocket subdomain to ensure DNS propagation.
- Use logs to check WebSocket server status and connection errors.
- Make sure the database and migrations are properly set, especially if using SQLite, by creating necessary files on your server.

Summary

Setting up Reverb with Laravel Forge involves local preparation of your Laravel application, provisioning and configuring a server on Forge, setting DNS for WebSocket subdomain, enabling Reverb through the Forge interface, and securing WebSocket connections with SSL. The Forge platform automates much of the daemon and WebSocket server setup, allowing real-time applications like chat or notifications to run seamlessly in production. Make sure your `.env` is properly configured and your deployment script includes Reverb restart commands for smooth operation. Testing locally and monitoring server daemons post-deployment can help ensure your real-time Laravel application runs efficiently on Forge.