Setting Up a WebSocket Server

Apache & Nginx (Ubuntu, CentOS, Debian, AlmaLinux)

WebSockets allow real-time communication between clients and the server. This guide explains how to set up a WebSocket server using Ratchet on different Linux distributions and configure it with Apache or Nginx.

How the WebSocket Server Works in JScms

The WebSocket server in JScms can be managed directly from the Administration Panel → Maintenance. It can be started, stopped, or restarted without needing manual intervention.

However, setting it up correctly ensures that it runs as a background service and remains active even after reboots or in some cases the permissions are available to run it from the administration panel. In this case you will have more options below.

Granting Permissions

To allow the web server user (www-data) to manage the WebSocket service, edit the sudoers file:

sudo visudo

Add the following line:

www-data ALL=(ALL) NOPASSWD: /bin/systemctl start websocket.service, /bin/systemctl stop websocket.service, 
/bin/systemctl restart websocket.service, /bin/systemctl is-active websocket.service

Creating the WebSocket Service

Create a systemd service file:

sudo nano /etc/systemd/system/websocket.service

Add the following:

[Unit]
Description=Ratchet WebSocket Server
After=network.target

[Service]
ExecStart=/usr/bin/php /path/to/core/DynamicWebSocket.php
WorkingDirectory=/path/to/core/
Restart=always
User=www-data
Group=www-data
StandardOutput=file:/path/to/core/tmp/DynamicWebSocket.log
StandardError=file:/path/to/core/tmp/DynamicWebSocket_error.log

[Install]
WantedBy=multi-user.target

Enabling and Starting the Service

Reload systemd and start the WebSocket service:

sudo systemctl daemon-reload
sudo systemctl enable websocket.service
sudo systemctl start websocket.service
sudo systemctl status websocket.service

Configuring WebSockets with Apache

Edit your Apache virtual host file:

sudo nano /etc/apache2/sites-available/000-default.conf

Add the following inside the block:

ProxyRequests Off
ProxyPass /ws ws://localhost:8081/
ProxyPassReverse /ws ws://localhost:8081/

Enable the necessary Apache modules and restart Apache:

sudo a2enmod proxy proxy_http proxy_wstunnel
sudo systemctl restart apache2

Configuring WebSockets with Nginx

Unlike Apache, Nginx requires additional configuration for WebSockets to work properly, especially handling the Upgrade and Connection headers correctly.

Edit your Nginx configuration file:

sudo nano /etc/nginx/sites-available/default

Add this inside the server {} block:

location /ws/ {
    proxy_pass http://localhost:8081/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    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;
}

Restart Nginx to apply the changes:

sudo systemctl restart nginx

WebSocket Server Configuration in JScms

In case you want to change the websocket port or the api key, you can do so in the configuration file, include/db.php:

define('JSCMS_API_KEY', 'NNdk2lfh3iusfj2hafjqjha3hj');
define('JSCMS_WS_PORT', '8081');

Optional – Auto-Restart with Crontab

In case the WebSocket server crashes unexpectedly, you can set up a basic fallback method using crontab. However, this is not necessary if the WebSocket server is managed through the JScms Administration Panel or through a daemon.

Edit the crontab file:

crontab -e

Add this line to restart the WebSocket server if it's not running:

* * * * * pgrep -f "DynamicWebSocket.php" > /dev/null || /usr/bin/php /path/to/core/DynamicWebSocket.php &

Common Issues and Troubleshooting

• WebSocket server does not start: Run sudo systemctl status websocket.service to check for errors.
• Clients can't connect: Ensure port 8081 is open in your firewall:

  sudo ufw allow 8081/tcp
  

• Nginx WebSockets not working: Ensure proxy_http_version 1.1 and the correct headers are set.

Need Help?

If you encounter issues, check the WebSocket log files in /path/to/core/tmp/ or your server error logs.