Socket service description

Socket 2 is a standalone WebSocket gateway for live Roxy-WI notifications. Roxy-WI publishes notifications to the roxy.notifications RabbitMQ exchange, Socket consumes them and forwards each message to browser sessions in the matching Roxy-WI group. The browser authenticates with a short-lived ticket issued by /socket-ticket.

Socket does not read the Roxy-WI user database and receives only the public half of the Roxy-WI JWT key. Notification and alert history remains durable in the Roxy-WI database; Socket provides immediate UI delivery and can be restarted without losing that history.

Socket requires an active User plan or higher, a working RabbitMQ connection and a Roxy-WI JWT public key.

# EL/RHEL-compatible systems
sudo dnf install roxy-wi-socket

# Debian/Ubuntu
sudo apt update
sudo apt install roxy-wi-socket
                

The package does not require Roxy-WI on the same host. Runtime options are in /etc/roxy-wi/socket.env. The default auto mode reads RabbitMQ settings from a local Roxy-WI installation when available. On a Socket-only host, set SOCKET_USE_ROXYWI_RABBITMQ_SETTINGS=0, provide all SOCKET_RABBITMQ_* connection values and copy the Roxy-WI JWT public key as shown below. The package listens on 127.0.0.1:8765 by default. If the reverse proxy is on another host, set SOCKET_LISTEN_HOST to a private address and allow port 8765 only from that proxy.

sudo install -m 0640 -o root -g roxy-wi-socket 
  /secure/source/roxy-wi-key.pub /etc/roxy-wi/socket-jwt-public.pem
# Set SOCKET_JWT_PUBLIC_KEY_FILE=/etc/roxy-wi/socket-jwt-public.pem
# in /etc/roxy-wi/socket.env, then:
sudo systemctl enable --now roxy-wi-socket
sudo systemctl status roxy-wi-socket
                

Copy only the Roxy-WI JWT public key to the Socket host and create a root-readable /etc/roxy-wi/socket.env file:

SOCKET_RABBITMQ_HOST=rabbitmq.internal
SOCKET_RABBITMQ_PORT=5672
SOCKET_RABBITMQ_VHOST=/roxy-wi
SOCKET_RABBITMQ_USER=roxy-wi
SOCKET_RABBITMQ_PASSWORD=GENERATED_STRONG_PASSWORD
SOCKET_JWT_ALGORITHM=RS256
SOCKET_JWT_PUBLIC_KEY_FILE=/run/roxy-wi/roxy-wi-key.pub
                

sudo chmod 600 /etc/roxy-wi/socket.env
docker run -d --name roxy-wi-socket --restart unless-stopped --stop-timeout 20 \
  --env-file /etc/roxy-wi/socket.env \
  --mount type=bind,src=/secure/path/roxy-wi-key.pub,dst=/run/roxy-wi/roxy-wi-key.pub,readonly \
  -p 127.0.0.1:8765:8765 \
  ghcr.io/roxy-wi/roxy-wi-socket:2.0.0
                

For Compose or Kubernetes, put RabbitMQ credentials in a Secret and mount the public key read-only. Never copy or mount the Roxy-WI private JWT key. Pin 2.0.0 or another tested version instead of relying on latest.

Keep the browser-visible Roxy-WI hostname unchanged and proxy only the /socket WebSocket path to Socket. The reverse proxy must preserve the WebSocket Upgrade and Connection headers. Do not expose RabbitMQ or port 8765 directly to the public internet.

When Socket runs on another host, route /socket through the Roxy-WI reverse proxy or an internal load balancer. Roxy-WI and every Socket replica must use the same RabbitMQ virtual host and the same JWT public key.

Socket is stateless and does not need its own database. Every replica creates an exclusive, auto-delete RabbitMQ queue, so every live notification reaches every replica and each replica forwards it only to its locally connected users. Put multiple replicas behind one WebSocket-capable load balancer.

Each replica must have a unique SOCKET_INSTANCE_ID. Containers and Kubernetes pods use their hostname by default, so do not set one shared value when scaling. Socket heartbeats, including runtime version, are published to roxy.events and displayed on Overview and Admin area => Tools.

# Package
/usr/bin/python3 /usr/lib/roxy-wi-socket/package_socket.py --version
journalctl -u roxy-wi-socket -f

# Container
docker run --rm ghcr.io/roxy-wi/roxy-wi-socket:2.0.0 --version
docker logs -f roxy-wi-socket
                

Version 2.0.0 and a fresh Socket heartbeat must appear in Roxy-WI. Open Roxy-WI in a browser and confirm that the /socket request upgrades to a WebSocket connection. HTTP 401 normally indicates an invalid or expired ticket; connection errors usually indicate reverse-proxy, RabbitMQ or public-key configuration problems.

Package-installed Socket can be updated with the package manager or from Admin area => Update. For containers and Kubernetes, change the pinned image tag and perform a Compose or Kubernetes rollout. Roxy-WI does not update remote container images. See the distributed-services update guide before replacing the old Socket service.