This document explains how to configure Monosign to work with a highly available (multi-node) monofor/mq cluster. Monosign connects to the cluster with a comma-separated host list, so it can fail over between nodes without any load balancer in front of the cluster.
Availability: Multi-node (cluster) deployments of monofor/mq will be supported starting with v2026.08. See How to Run monofor/mq (RabbitMQ) for how to set up the cluster itself.
Prerequisites
Before configuring Monosign, make sure the following are in place: a running monofor/mq cluster with an odd number of nodes (e.g., 3 or 5) so the cluster can keep a majority (quorum); each node placed on a different worker (host); and the same credentials (MONOFOR_MQ_USER / MONOFOR_MQ_PASSWORD) valid on all nodes. All cluster nodes must be reachable from every Monosign component on the MQ port (default 5672).
Configuration
Monosign uses the MONOSIGN_MQ_* environment variables. For an HA cluster, set MONOSIGN_MQ_HOST to the comma-separated list of all cluster nodes:
|
Variable |
Value for HA |
Description |
|---|---|---|
|
|
|
Comma-separated list of all cluster node hostnames (or IPs). Monosign will connect to an available node and fail over to another node if the connection is lost. |
|
|
|
MQ port. The same port is used for all listed hosts, so every node must listen on the same port. |
|
|
|
Must match the cluster credentials ( |
|
|
|
Must match the cluster password ( |
Example
MONOSIGN_MQ_HOST=mq1,mq2,mq3
MONOSIGN_MQ_PORT=5672
MONOSIGN_MQ_USERNAME=monofor
MONOSIGN_MQ_PASSWORD=<YOUR_STRONG_PASSWORD>
Do not list only one node of the cluster. If the listed node goes down, Monosign cannot fail over to the remaining nodes even though the cluster itself is still healthy. Always list all cluster nodes.
Apply the same MONOSIGN_MQ_* values to every Monosign component that uses the environment file (API, Management, Account, Service). If the components share a common env file (e.g., monosign.env), updating it once is enough — then restart the containers so the new values take effect.
Failure Behavior
With this configuration, the behavior during node failures is as follows. If the node Monosign is connected to fails, Monosign reconnects to one of the other listed nodes automatically. The cluster stays operational as long as a majority of nodes is running — a 3-node cluster tolerates the loss of 1 node, a 5-node cluster tolerates the loss of 2. If the cluster loses its majority (e.g., 2 of 3 nodes down), the remaining node cannot serve traffic safely; restore the failed nodes to recover.
Verification
After restarting the Monosign components, verify the setup: check the container logs of the Monosign services for successful MQ connection messages and make sure there are no connection-refused or authentication errors. To test failover, stop one monofor/mq node and confirm in the logs that Monosign reconnects to another node and continues processing.