Configure the built-in Web Sockets server

Use the built-in web sockets server to receive real-time updates and notifications.

The web sockets server allows real-time communication between the server and the web browser. In order to use the built-in web sockets server, you will need a virtual private server or a dedicated server where you can install the required dependencies and perform server configurations.

You will notice that the built-in web sockets server uses the same environment configuration as Pusher, this is because the server is a drop-in replacement and alternative to Pusher.

Please consider using Pusher instead if:

• you are already using Pusher as part of your business operations
• you are using a shared hosting service
• you do not have access to the server's terminal or console
• you do not know how to perform the listed server configurations

What you will need

1. SSH access to your server
2. Root or sudo access (sudo is recommended)
3. Queues configured and running
4. Supervisor installed on your server

Before we start

For this guide, we assume that the help desk is installed at /var/www/fullhelp/live.

In order for the web socket server to listen to new connections, the php artisan websockets:serve command should be executed at the root directory of the installation. Note that once the websockets:serve command has started, it will continue to run until it is manually stopped or you close your terminal.

To keep the websockets:serve process running permanently in the background, we will use the process monitor, Supervisor, to ensure that the built-in web sockets server worker does not stop running.

Enable and configure the built-in web sockets server

To enable the built-in web socket server, simply set BROADCAST_DRIVER to builtin in the .env file: 

BROADCAST_DRIVER=builtin

Additionally, set PUSHER_HOST to your help desk's host. Assuming you are accessing your help desk using http://desk.domain.com/en/login the host would be desk.domain.com:

PUSHER_HOST=desk.domain.com

Supervisor configuration

Installing Supervisor

Supervisor is a process monitor for the Linux operating system, and will automatically restart your websockets:serve process if it fails. To install Supervisor on Ubuntu, you may use the following command:

sudo apt-get install supervisor

Configuring Supervisor

Supervisor configuration files are typically stored in the /etc/supervisor/conf.d directory. Within this directory, you may create any number of configuration files that instruct Supervisor how your processes should be monitored. For this guide, let's create /etc/supervisor/conf.d/fullhelp.conf and add the following content:

[program:fullhelp-ws-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/fullhelp/live/artisan websockets:serve --port=6001
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/fullhelp/live/storage/logs/worker.log

Replace /var/www/fullhelp/live with the path to the help desk installation.

The --port option can also be changed based on your needs; 6001 is the default port used by the built-in web sockets server. If you select a port other than 6001, make sure to add PUSHER_PORT=your-port to the .env file.

Starting Supervisor

Once the configuration file is in place, start the process using the following commands:

sudo supervisorctl reread

sudo supervisorctl update

sudo supervisorctl start fullhelp-ws-worker:*

For more information on Supervisor, consult the Supervisor documentation.

SSL configuration

If you have configured HTTPS for your help desk software, you may also want to secure the web sockets connections. 

These are high-level instructions and should be adapted to each environment. In most cases, SSL is provided by Let's Encrypt, so we are going to use it as an example.

First, add the following settings to the .env file:

• WEBSOCKETS_LOCAL_CERT: Path to local certificate file on the filesystem. It must be a PEM encoded file that contains your certificate and private key. It can optionally contain the certificate chain of issuers. The private key also may be contained in a separate file specified by WEBSOCKETS_LOCAL_PRIVATE_KEY.
• WEBSOCKETS_LOCAL_PRIVATE_KEY: Path to the local private key file on the filesystem in case of separate files for the certificate (WEBSOCKETS_LOCAL_CERT) and private key.

See the following example:

WEBSOCKETS_LOCAL_CERT="/etc/letsencrypt/live/desk.mydomain.com/fullchain.pem"
WEBSOCKETS_LOCAL_PRIVATE_KEY="/etc/letsencrypt/live/desk.mydomain.com/privkey.pem"

Once you add the certificate file paths, enable HTTPS for WebSocket connections by adding the following to the .env file:

PUSHER_ENCRYPTED=true
PUSHER_SCHEME=https

A note to CloudFlare users:

The port 6001 will not work when using Cloudflare Proxy. Change it to one of the allowed secure ports, for example 2053. Remember to update the Supervisor configuration and the .env file.

Troubleshooting

The built-in web sockets server may not work correctly for several reasons, the most common reasons are:

1. limited privileges
2. firewall protection
3. not being able to use the port specified
4. web sockets server not running
5. queues not running
6. incorrect BROADCAST_DRIVER configuration value, see the Enable the Built-In Web Socket Server section

Determining the real cause of a problem and the solution will vary considerably by what server is in use and the configurations.