Local MQ Container¶

A containerized IBM MQ environment provides two queue managers for development and integration testing.

Prerequisites¶

Docker Desktop or compatible Docker Engine.
IBM MQ container image access (license acceptance required).
The mq-rest-admin-dev-environment repository cloned as a sibling directory (../mq-rest-admin-dev-environment), or set MQ_DEV_ENV_PATH to its location.

Configuration¶

The Docker Compose file in the mq-rest-admin-dev-environment repository runs two queue managers on a shared network (mq-dev-net):

Setting	QM1	QM2
Queue manager	`QM1`	`QM2`
MQ listener port	`1414`	`1415`
REST API port	`9443`	`9444`
Container name	`mq-dev-qm1`	`mq-dev-qm2`

Note

Some language repos use offset ports (e.g. 9453/9454, 1424/1425) to allow running integration tests for multiple repos simultaneously without port conflicts. See the language-specific notes below for details.

Both queue managers share the same credentials:

Setting	Value
Admin credentials	`mqadmin` / `mqadmin`
Read-only credentials	`mqreader` / `mqreader`
QM1 REST base URL	`https://localhost:9443/ibmmq/rest/v2`
QM2 REST base URL	`https://localhost:9444/ibmmq/rest/v2`

Quick start¶

Start both queue managers:

./scripts/dev/mq_start.sh

Seed deterministic test objects on both QMs (all prefixed with DEV.):

./scripts/dev/mq_seed.sh

Verify REST-based MQSC responses on both QMs:

./scripts/dev/mq_verify.sh

Seed objects¶

QM1 receives the full set of test objects (queues, channels, topics, namelists, listeners, processes) plus cross-QM objects for communicating with QM2. QM2 receives a smaller set of objects plus the reciprocal cross-QM definitions.

The seed scripts are maintained in the mq-rest-admin-dev-environment repository at seed/base-qm1.mqsc and seed/base-qm2.mqsc. Both use REPLACE so they can be re-run at any time without side effects.

Lifecycle scripts¶

Script	Purpose
`scripts/dev/mq_start.sh`	Start both queue managers and wait for REST readiness
`scripts/dev/mq_seed.sh`	Seed deterministic test objects on both QMs
`scripts/dev/mq_verify.sh`	Verify REST-based MQSC responses on both QMs
`scripts/dev/mq_stop.sh`	Stop both queue managers
`scripts/dev/mq_reset.sh`	Reset to clean state (removes data volumes)

Environment variables¶

Variable	Default	Description
`MQ_REST_BASE_URL`	`https://localhost:9443/ibmmq/rest/v2`	QM1 REST API base URL
`MQ_REST_BASE_URL_QM2`	`https://localhost:9444/ibmmq/rest/v2`	QM2 REST API base URL
`MQ_ADMIN_USER`	`mqadmin`	Admin username
`MQ_ADMIN_PASSWORD`	`mqadmin`	Admin password
`MQ_IMAGE`	`icr.io/ibm-messaging/mq:latest`	Container image
`MQ_DEV_ENV_PATH`	`../mq-rest-admin-dev-environment`	Path to mq-rest-admin-dev-environment project

Gateway routing¶

The two-QM local setup supports gateway routing out of the box. The seed scripts create QM aliases and sender/receiver channels so each queue manager can route MQSC commands to the other.

curl example¶

Query QM2's queue manager attributes through QM1's REST API:

curl -k -u mqadmin:mqadmin \
  -H "Content-Type: application/json" \
  -H "ibm-mq-rest-csrf-token: local" \
  -H "ibm-mq-rest-gateway-qmgr: QM1" \
  -d '{"type": "runCommandJSON", "command": "DISPLAY", "qualifier": "QMGR"}' \
  https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM2/mqsc

Reset workflow¶

To return to a completely clean state (removes both data volumes):

./scripts/dev/mq_reset.sh

Troubleshooting¶

If the REST API is not reachable, ensure the embedded web server is binding to all interfaces:

docker compose -f ../mq-rest-admin-dev-environment/config/docker-compose.yml exec -T qm1 \
    setmqweb properties -k httpHost -v "*"

Then restart the containers and retry the verification workflow.

Python-specific notes¶

Integration tests¶

Integration tests are opt-in and require running MQ containers:

PYMQREST_RUN_INTEGRATION=1 uv run pytest -m integration

When enabled, the test session:

Starts both local MQ containers.
Waits for both REST endpoints to become ready.
Seeds deterministic test objects on both QMs.
Runs DISPLAY checks plus define/alter/delete lifecycles.
Stops both containers after the session.

Environment variables¶

Variable	Default	Description
`MQ_REST_BASE_URL`	`https://localhost:9443/ibmmq/rest/v2`	QM1 REST API base URL
`MQ_REST_BASE_URL_QM2`	`https://localhost:9444/ibmmq/rest/v2`	QM2 REST API base URL
`MQ_ADMIN_USER`	`mqadmin`	Admin username
`MQ_ADMIN_PASSWORD`	`mqadmin`	Admin password
`MQ_IMAGE`	`icr.io/ibm-messaging/mq:latest`	Container image

Gateway routing with pymqrest¶

from pymqrest import MQRESTSession
from pymqrest.auth import BasicAuth

# Route commands to QM2 through QM1
session = MQRESTSession(
    rest_base_url="https://localhost:9443/ibmmq/rest/v2",
    qmgr_name="QM2",
    credentials=BasicAuth("mqadmin", "mqadmin"),
    gateway_qmgr="QM1",
    verify_tls=False,
)

qmgr = session.display_qmgr()
print(qmgr)  # QM2's attributes, routed through QM1