RabbitMQ-server

RabbitMQ is the message broker between Roxy-WI and independently deployed services. It allows Roxy-WI, Checker, Metrics and Socket to run on different servers without sharing application code or a database.

Never expose AMQP port 5672 or the management interface to the public Internet. Put RabbitMQ and all workers on a trusted private network or VPN and use a unique generated password. The default guest account is not suitable for remote workers.

• Roxy-WI publishes desired Checker and Metrics state to durable queues through the roxy.commands exchange.
• Checker and Metrics keep assignments in their own databases, run the checks continuously and publish heartbeats and results to roxy.events.
• Roxy-WI stores service events, Checker history and Metrics samples in its database. RabbitMQ is transport, not the user-visible history store.
• Roxy-WI publishes live UI notifications to roxy.notifications; every Socket replica forwards them to its connected browser sessions.

RabbitMQ retains commands while a worker is offline. After a restart, Checker and Metrics recover their desired state and expired leases from their service-owned database. Do not create a separate command queue for every replica: replicas in one logical worker pool share the service queue and service database.

Use a currently supported RabbitMQ release and follow the official repository instructions for your operating system:

• Debian and Ubuntu
• RHEL, CentOS Stream, Rocky Linux, AlmaLinux, Oracle Linux and Amazon Linux
• Other installation methods and container images

sudo systemctl enable --now rabbitmq-server
sudo rabbitmq-diagnostics -q ping
                

A minimal Compose service uses persistent storage and keeps ports on a private network:

services:
  rabbitmq:
    image: rabbitmq:4-management
    hostname: rabbitmq-1
    restart: unless-stopped
    environment:
      RABBITMQ_DEFAULT_USER: roxy-wi
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:?set RABBITMQ_PASSWORD}
      RABBITMQ_DEFAULT_VHOST: /roxy-wi
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq

volumes:
  rabbitmq-data:
                

Create a dedicated virtual host and application user for an existing package installation:

sudo rabbitmqctl add_vhost /roxy-wi
sudo rabbitmqctl add_user roxy-wi 'GENERATED_STRONG_PASSWORD'
sudo rabbitmqctl set_permissions -p /roxy-wi roxy-wi ".*" ".*" ".*"
                

Store passwords in a secret manager or root-readable environment files. Every Roxy-WI web replica, scheduler, event consumer, Checker, Metrics and Socket instance must use the same virtual host. They may share one application account or use separate RabbitMQ users with equivalent permissions. Rotate a credential on every component that uses it before deleting the old credential.

Open Admin area => Settings => RabbitMQ and set:

The legacy rabbitmq_queue field does not replace the distributed-service queues; leave it at its current value. Containerized Roxy-WI instances may use ROXYWI_RABBITMQ_HOST, ROXYWI_RABBITMQ_PORT, ROXYWI_RABBITMQ_VHOST, ROXYWI_RABBITMQ_USER and ROXYWI_RABBITMQ_PASSWORD instead of database settings.

sudo systemctl enable --now roxy-wi-scheduler roxy-wi-service-events
sudo systemctl restart roxy-wi-scheduler roxy-wi-service-events
                

Service packages do not require the Roxy-WI package. Their default *_USE_ROXYWI_RABBITMQ_SETTINGS=auto mode reuses the Admin-area connection only when a local /etc/roxy-wi/roxy-wi.cfg exists. On a worker-only host, set the option to 0 in /etc/roxy-wi/checker.env, metrics.env or socket.env and provide explicit values:

# Use CHECKER_, METRICS_ or SOCKET_ as the connection prefix
CHECKER_USE_ROXYWI_RABBITMQ_SETTINGS=0
CHECKER_RABBITMQ_HOST=rabbitmq.internal
CHECKER_RABBITMQ_PORT=5672
CHECKER_RABBITMQ_VHOST=/roxy-wi
CHECKER_RABBITMQ_USER=roxy-wi
CHECKER_RABBITMQ_PASSWORD=GENERATED_STRONG_PASSWORD

# Queue type applies to Checker and Metrics durable command queues
CHECKER_RABBITMQ_QUEUE_TYPE=classic
                

Queue type must match on Roxy-WI and every Checker or Metrics worker. The Roxy-WI equivalent is ROXYWI_RABBITMQ_QUEUE_TYPE. A mismatch causes RabbitMQ queue declaration errors.

RPM and DEB units run under dedicated roxy-wi-checker, roxy-wi-metrics and roxy-wi-socket users and do not use /var/www/haproxy-wi. After editing a standalone configuration, run systemctl enable --now roxy-wi-checker (or the corresponding service name).

• Use classic queues for a single RabbitMQ node.
• Use quorum queues with a properly operated multi-node RabbitMQ cluster; set the same value on all applications before queues are created.
• Use durable storage, monitoring and tested backups. RabbitMQ HA does not replace the separate Checker and Metrics state databases.
• Run multiple Roxy-WI web replicas against one application database and the same RabbitMQ virtual host.

Changing an existing queue from classic to quorum is a migration, not an in-place toggle. Drain the services, recreate the affected queues with the new type, then restart Roxy-WI and the workers.

sudo rabbitmq-diagnostics -q ping
sudo rabbitmqctl list_queues -p /roxy-wi name messages_ready messages_unacknowledged consumers
sudo journalctl -u roxy-wi-scheduler -u roxy-wi-service-events --since "10 minutes ago"
                

Healthy deployments normally show consumers for roxy-checker.commands, roxy-metrics.commands and roxy-wi.service-events. Worker heartbeats and versions appear on Overview and Admin area => Tools.

• Authentication failed: verify the user, password, virtual host and permissions on both sides.
• Queue declaration failed: make sure every component uses the same classic or quorum queue type.
• Worker is running but has no assignments: verify the subscription, restart the Roxy-WI scheduler after an upgrade and wait one reconciliation cycle.
• Heartbeat is missing: check the roxy-wi-service-events consumer and the worker logs.