How to Run monofor/mq (RabbitMQ)

This document explains how to run the monofor/mq container image (based on RabbitMQ), both as a single node and as a multi-node cluster. It covers all supported environment variables, Docker Compose examples, and compatibility notes for the official RabbitMQ image variables.

monofor/mq is configured entirely through environment variables. For a single node, only credentials are required. Clustering is enabled simply by setting MONOFOR_MQ_CLUSTER_NODES.

Credentials

Variable	Required	Default	Description
`MONOFOR_MQ_USER`	No	`monofor`	Default username.
`MONOFOR_MQ_PASSWORD`	Yes	—	Password for the default user. Alternatively use `MONOFOR_MQ_PASSWORD_FILE` to read the password from a mounted secret file. The `_FILE` variant takes precedence when both are set.

Single Node

Only credentials are required — set MONOFOR_MQ_PASSWORD (and optionally MONOFOR_MQ_USER) and start the container. No clustering variables are needed; the Erlang cookie is auto-generated.

Docker run

Bash

docker run -d \
  --name monofor-mq \
  --hostname monofor-mq \
  -e MONOFOR_MQ_USER=monofor \
  -e MONOFOR_MQ_PASSWORD='<YOUR_STRONG_PASSWORD>' \
  -p 5672:5672 \
  -v monofor-mq-data:/var/lib/rabbitmq \
  monofor/mq:latest

Docker Compose

YAML

services:
  mq:
    image: monofor/mq:latest
    hostname: monofor-mq
    environment:
      MONOFOR_MQ_USER: monofor
      MONOFOR_MQ_PASSWORD_FILE: /run/secrets/mq_password
    secrets:
      - mq_password
    ports:
      - "5672:5672"
    volumes:
      - mq-data:/var/lib/rabbitmq

secrets:
  mq_password:
    file: ./secrets/mq_password.txt

volumes:
  mq-data:

Adjust the image reference and tag to match the registry you pull from. Using the _FILE secret variant is recommended over putting the password directly in the compose file.

Multi Node (Cluster)

Availability: Multi-node (cluster) deployments will be supported starting with v2026.08. Until that release, run monofor/mq as a single node. The variables and examples below describe the upcoming cluster support.

Node placement and majority: Each cluster node should be placed on a different worker (host) — running multiple nodes on the same worker means a single host failure can take down more than one node. Majority (quorum) is important for monofor/mq: the cluster must keep a majority of nodes running to operate safely, so always deploy an odd number of nodes (e.g., 3 or 5). A 3-node cluster tolerates the loss of 1 node; a 5-node cluster tolerates the loss of 2.

Variable	Required	Default	Description
`MONOFOR_MQ_CLUSTER_NODES`	Yes (for clustering)	—	Comma-separated node list. Setting this variable enables clustering.
`MONOFOR_MQ_COOKIE`	Yes (for clustering)	—	Shared cluster secret. Must be set explicitly and be identical on all nodes. Alternatively use `MONOFOR_MQ_COOKIE_FILE` for a mounted secret file; the `_FILE` variant takes precedence.
`MONOFOR_MQ_CLUSTER_PARTITION_HANDLING`	No	`autoheal`	Network partition handling strategy.

The cluster cookie is not auto-generated in cluster mode. It must be provided explicitly and must be the same value on every node — nodes with different cookies cannot join the cluster.

Example: 3-node cluster (Docker Compose)

YAML

x-mq-common: &mq-common
  image: monofor/mq:latest
  environment: &mq-env
    MONOFOR_MQ_USER: monofor
    MONOFOR_MQ_PASSWORD_FILE: /run/secrets/mq_password
    MONOFOR_MQ_COOKIE_FILE: /run/secrets/mq_cookie
    MONOFOR_MQ_CLUSTER_NODES: mq1,mq2,mq3
    MONOFOR_MQ_CLUSTER_PARTITION_HANDLING: autoheal
  secrets:
    - mq_password
    - mq_cookie

services:
  mq1:
    <<: *mq-common
    hostname: mq1
    volumes: [ mq1-data:/var/lib/rabbitmq ]
  mq2:
    <<: *mq-common
    hostname: mq2
    volumes: [ mq2-data:/var/lib/rabbitmq ]
  mq3:
    <<: *mq-common
    hostname: mq3
    volumes: [ mq3-data:/var/lib/rabbitmq ]

secrets:
  mq_password:
    file: ./secrets/mq_password.txt
  mq_cookie:
    file: ./secrets/mq_cookie.txt

volumes:
  mq1-data:
  mq2-data:
  mq3-data:

In orchestrated environments, enforce the one-node-per-worker placement: in Docker Swarm use deploy.placement constraints, and in Kubernetes and OpenShift use pod anti-affinity (or topologySpreadConstraints) so the scheduler never co-locates two monofor/mq nodes on the same worker. OpenShift uses the same scheduling mechanisms as Kubernetes, so the identical anti-affinity / topologySpreadConstraints configuration applies — just make sure the deployment also complies with OpenShift's Security Context Constraints (SCCs), e.g. by allowing the required runtime uid/gid (PUID/PGID, default 1001) or using the SKIP_DROP_PRIVS/SKIP_FIX_PERMS escape hatches when running under restricted SCC with a random uid.

Compatibility & Advanced

Official RabbitMQ image variables

The official RabbitMQ image variables are still honored for backwards compatibility, but only when the corresponding MONOFOR_MQ_* variable is not set:

Official variable	Overridden by
`RABBITMQ_DEFAULT_USER`	`MONOFOR_MQ_USER`
`RABBITMQ_DEFAULT_PASS`	`MONOFOR_MQ_PASSWORD` / `MONOFOR_MQ_PASSWORD_FILE`
`RABBITMQ_ERLANG_COOKIE`	`MONOFOR_MQ_COOKIE` / `MONOFOR_MQ_COOKIE_FILE`
`RABBITMQ_CLUSTER_NODES`	`MONOFOR_MQ_CLUSTER_NODES`

Runtime user and permissions

Variable	Default	Description
`PUID` / `PGID`	`1001`	Runtime uid/gid the service runs as.
`SKIP_DROP_PRIVS=1`	—	Escape hatch: skip dropping privileges (same behavior as `monofor/cache`).
`SKIP_FIX_PERMS=1`	—	Escape hatch: skip fixing data directory permissions (same behavior as `monofor/cache`).

Quick Reference

Scenario	Minimum required variables
Single node	`MONOFOR_MQ_PASSWORD` (or `MONOFOR_MQ_PASSWORD_FILE`)
Cluster node (from v2026.08)	`MONOFOR_MQ_PASSWORD`, `MONOFOR_MQ_CLUSTER_NODES`, `MONOFOR_MQ_COOKIE` (identical on all nodes)