MQ Resiliency Lab for Linux
A downloadable, signed lab that stands up IBM MQ high-availability (HA) and
disaster-recovery (DR) topologies end to end — from a bare x86 Linux host down
to running queue managers and a live message path that survives failover. You
bring a virtualization-capable host; the lab brings everything else, and stands
up a full HA/DR stack with one command.
Full documentation lives in the site under docs/site/ —
this README is the on-ramp; the site is the depth.
Table of Contents
What this is
At the core is mqlab, a standalone Python orchestrator, plus its support
tree — the Ansible roles that provision everything from OS to running queue
managers, the lab/topology.yaml fleet definition, and the
release manifests. The deliverable is the whole tree, not a Python module:
you run it from the extracted, signed release.
mqlab does the opposite of most tooling — rather than hiding the mechanics, it
shows them. Every command it runs (virsh, Ansible, runmqsc) is printed
verbatim as it runs and teed to a transcript, so you can watch a step, understand
it, then reproduce it by hand. The lab is transparent evidence, not a black box.
The author develops the lab inside a personal
Vergil dev VM, but Vergil only provides that
dev environment — strip it away and what remains is exactly mqlab and its
support tree, which is what the signed release ships and what you run on your own
host. See Developing with Vergil below.
Getting Started
This is the orientation-altitude version of the site's
Getting Started — start there for the full
walkthrough.
Prerequisites
Almost everything is fetched automatically — IBM MQ Advanced for Developers
(the no-charge edition) is pulled by the tooling, at the level pinned in
lab/mq-version (currently 10.0.1.0). You provide:
- An x86-64 Linux host with root/sudo and nested virtualization — the lab
creates nested libvirt/QEMU/Vagrant guests and wants a beefy box (roughly
12 vCPU / 64 GiB).
mqlab doctor reports anything missing.
- uv and Python 3.14 — the orchestrator's
runtime (
uv provisions its own pinned 3.14; the base OS Python is untouched).
- libvirt / QEMU / Vagrant — the virtualization stack the guests run on.
- gpg — to verify the signed release below.
- A RHEL subscription — only for the RHEL-based arms (RDQM, Native HA on
RHEL). The canonical
pcmk-ubuntu arm needs nothing extra. Both RHEL arms
default to RHEL 10, which needs an x86-64-v3 CPU (mqlab doctor says
whether yours is one); without it, build them on RHEL 9 instead.
Each stack's default and selectable OS versions (Ubuntu 24.04/26.04, RHEL 9/10)
live in one catalog, lab/versions.yaml; the site's
Getting Started shows
how to pick one.
Download and verify the release
The lab ships as a signed tarball from the
Releases page.
Download the tarball and the two checksum files (substitute the version you're
installing):
VERSION=vX.Y.Z
base=https://github.com/logical-minds-foundry/mq-resiliency-lab-for-linux/releases/download/$VERSION
curl -LO $base/mq-resiliency-lab-for-linux-$VERSION.tar.gz
curl -LO $base/SHA256SUMS
curl -LO $base/SHA256SUMS.asc
Verify it before you unpack. The trust root is the fingerprint below plus
a key fetched out-of-band — not any key bundled in the tarball:
gpg --recv-keys 5BABD50A78EBF24D2410AE52ADF1A99B75D24E54 # or import the key from the release page over HTTPS
gpg --fingerprint 5BABD50A78EBF24D2410AE52ADF1A99B75D24E54 # cross-check it matches this README
gpg --verify SHA256SUMS.asc SHA256SUMS # the checksums are signed by that key
sha256sum -c SHA256SUMS # the tarball matches the checksums
Once both checks pass, unpack the tarball and enter the tree:
tar xzf mq-resiliency-lab-for-linux-$VERSION.tar.gz
cd mq-resiliency-lab-for-linux-$VERSION
Run it
From inside the extracted tree, build the environment, pre-flight the host, then
bring up your first stack:
./scripts/setup # checks uv + Python 3.14, then runs `uv sync` to build the venv
. .venv/bin/activate # put `mqlab` (and its companion tools) on PATH
mqlab doctor # pre-flight the host: arch, KVM, libvirt, required tools
mqlab bootstrap pcmk-ubuntu # bring up a full HA/DR stack: net → vms → provision → observe
mqlab status pcmk-ubuntu # phase completion (✓/✗) for this stack
./scripts/setup sets up the environment, not the lab: it verifies uv and
a uv-managed Python 3.14 are present (installing 3.14 via uv if missing), runs
uv sync to materialize the
virtual environment, and prints the next commands. It cannot change your shell's
PATH, so activate the venv (or prefix each command with uv run). mqlab bootstrap pcmk-ubuntu
then sequences the whole bring-up — the canonical starting arm is pcmk-ubuntu
(Pacemaker/SAN on Ubuntu, subscription-free and x86-native) — and leaves you with
a running queue manager. See
Getting Started to send your first message
and watch it survive a failover.
Developing with Vergil
The lab is developed inside an ephemeral Vergil
VM — the author's personal, solo-practitioner dev tooling — rather than on the
host directly. That is a development convenience, not part of the consumer
path above: strip Vergil away and what remains is exactly the tree you unpacked.
It's my own tooling; if you'd find it useful, talk to me.
Development
Developing the lab itself (as distinct from running it) uses the Vergil
workflow. Footprint and tooling are declared as the [vm.vergil-user] profile in
vergil.toml; build and enter the box with:
vrg-vm create logical-minds-foundry/mq-resiliency-lab-for-linux --identity vergil-user
vrg-vm session logical-minds-foundry/mq-resiliency-lab-for-linux --identity vergil-user
The box is ephemeral and fully reproducible, so don't hand-customize it.
Nothing in it outside the host-mounted build/ directory is precious;
re-provision it freely to stay fresh:
vrg-vm rebuild logical-minds-foundry/mq-resiliency-lab-for-linux --identity vergil-user
To change its tooling, edit the [vm.vergil-user] profile and rebuild; never
apt install inside a live VM.
From a dev checkout, run the CLI as uv run mqlab … rather than calling the
venv's mqlab by its path: uv run puts the venv's bin/ on PATH, so the
tools mqlab calls by bare name resolve (see
docs/development/operating-the-lab-from-a-dev-session.md).
See CLAUDE.md for the workflow,
docs/site/docs/develop.md for the developer
on-ramp, docs/development/release-runbook.md
for cutting a release, and
docs/development/perf-and-staging.md
for comparing bootstrap perf reports across macOS and x86 cloud
(mqlab perf diff, the auto-detected MQLAB_ENV profiles, macOS huge pages, and
measured bootstrap times).
