Running a Websocket Server

For the platform to be able to broadcast events and for your client apps to receive them you will need to connect to a websocket server. The websocket server handles connections from your platform and client apps and facilitates the transfer of data from the events to your clients apps. There are several option available, including open source solutions as well as paid for services (e.g. Pusher). Here we will show how to setup the open source Laravel Websockets package to run a server locally. The Laravel Websockets package has full feature parity with the Pusher WebSocket and HTTP API meaning you can use it as a direct replacement, and should you decide to scale to a paid for solution via Pusher in future there would be minimal work involved in making the switch.

1. Start by requiring the Laravel Websockets package into your project from the root folder:

cd /var/www/laravel/
  
composer require beyondcode/laravel-websockets

2. Next publish and run the package migrations:

php artisan vendor:publish --provider="BeyondCode\LaravelWebSockets\WebSocketsServiceProvider" --tag="migrations"

php artisan migrate

3. Next, you need to publish the WebSocket configuration file:

php artisan vendor:publish --provider="BeyondCode\LaravelWebSockets\WebSocketsServiceProvider" --tag="config"

The default configuration should suffice for most purposes, however you may want to change the path variable in the config/websockets.php file to something different, this path is what will be used to register your websocket routes, and is also used to access the stats dashboard when running the platform in local mode (APP_ENV=local in your .env file).

4. Now you can configure the websocket endpoint you'd like to use. Do this by setting the pusher vars in your .env file. The ID can be any number, and the secret can be any value you choose. If you decide to migrate to Pusher's paid for service in future then you will get these values from your account there. In the meantime set them to any random value. The PUSHER_APP_KEY will be used to create the websocket endpoint:

BROADCAST_DRIVER=pusher

PUSHER_APP_ID=13453
PUSHER_APP_KEY=websocket
PUSHER_APP_SECRET=bc285352-c7b8-4ef8-9745-18b12ec35abf
PUSHER_APP_CLUSTER=mt1

5. When broadcasting events from your Laravel application to your WebSocket server, the default behavior is to send the event information to the official Pusher server. But since the Laravel WebSockets package comes with its own Pusher API implementation, we need to tell Laravel to send the events to our own server.
   To do this, you should add the host and port configuration key to your config/broadcasting.php and add it to the pusher section. The default port of the Laravel WebSocket server is 6001.

'pusher' => [
    'driver' => 'pusher',
    'key' => env('PUSHER_APP_KEY'),
    'secret' => env('PUSHER_APP_SECRET'),
    'app_id' => env('PUSHER_APP_ID'),
    'options' => [
        'cluster' => env('PUSHER_APP_CLUSTER'),
        'encrypted' => false,
        'host' => '127.0.0.1',
        'port' => 6001,
        'scheme' => 'http'
    ],
],

6. Once you have configured your WebSocket apps and Pusher settings, you can start the Laravel WebSocket server by issuing the following artisan command, it would be recommended to run this in another pane in tmux as we did before when running the platform workers:

php artisan websockets:serve

7. Your websocket server is now running and you can now connect to it using the following URI:
   ws://your-domain.com:6001/app/your-pusher-app-key
   There are some browser extensions available which will allow you to connect to your websocket and see data flowing through it, which is useful for debugging.

📘

For extra security it would be recommended to also enable secure websocket (WSS) connections.

To help secure your websocket follow these steps to enable wss:

1. Log into your server and then open up the nginx config file for your site in nano. You can find this in the path /etc/nginx/sites-enabled/laravel You will need to use sudo mode for this so if you are not logging as the root user have your login user password handy to be able save the edits.

sudo nano /etc/nginx/sites-enabled/laravel

2. Add this definition to the end of first server { } block, below the line that reads ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot and before the closing curly brace:

    location ~ /app/.* {
        proxy_pass             http://127.0.0.1:6001$1;
        proxy_set_header Host  $host;
        proxy_read_timeout     60;
        proxy_connect_timeout  60;
        proxy_redirect         off;

        # Allow the use of websockets
        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;
    }

3. Save the file with ctrl-x y and then restart the nginx server with this command:

sudo service nginx restart

4. Finally connect to your workers tmux session and start (or stop and restart) the websocket server.

tmux a -t workers

// Use ctrl-b up-arrown / down-arrow to select the pane with the websocket server

ctrl-c // if already running

php artisan websockets:serve

You should now be able to connect to your websocket sever on port 443 using the wss schema e.g. wss://your-platform-domain.com/app/websocket