Dev Services

Dev Services automatically start a local MQTT broker (in a container) while you develop or test, so you don’t need to install or configure one yourself. Your messaging channels are wired to it transparently.

When are Dev Services used?

Dev Services for MQTT are enabled by default in dev and test mode, and start a broker unless the connection is already configured — that is, unless a host (or port) is set for one of the smallrye-mqtt-hivemq channels.

They require a working container runtime (Docker or Podman). To disable them explicitly:

# Disable all Dev Services
quarkus.devservices.enabled=false

# ...or only the MQTT one
quarkus.hivemq.devservices.enabled=false

Configuration

All Dev Services options are build-time properties under quarkus.hivemq.devservices.*:

# Explicitly enable/disable the MQTT Dev Service
quarkus.hivemq.devservices.enabled=true

# Container image to use (HiveMQ Community Edition by default)
quarkus.hivemq.devservices.image-name=hivemq/hivemq-ce:2024.3

# Fixed broker port (omit or leave unset to get a random free port)
quarkus.hivemq.devservices.port=1883

# Share the broker across applications/tests (dev mode only)
quarkus.hivemq.devservices.shared=true

# Label value used for container discovery when shared=true
quarkus.hivemq.devservices.service-name=mqtt

# Extra environment variables passed to the broker container
quarkus.hivemq.devservices.container-env.HIVEMQ_LOG_LEVEL=INFO

Property Description Default

Property	Description	Default
`quarkus.hivemq.devservices.enabled`	Enable/disable the MQTT Dev Service.	(auto)
`quarkus.hivemq.devservices.image-name`	Broker image.	`hivemq/hivemq-ce:2024.3`
`quarkus.hivemq.devservices.port`	Fixed host port; random if unset.	(random)
`quarkus.hivemq.devservices.shared`	Reuse a running broker across apps/tests (dev mode).	`true`
`quarkus.hivemq.devservices.service-name`	`quarkus-dev-service-mqtt` label value used for discovery.	`mqtt`
`quarkus.hivemq.devservices.container-env.*`	Environment variables passed to the container.	—

quarkus.hivemq.devservices.enabled

Enable/disable the MQTT Dev Service.

(auto)

quarkus.hivemq.devservices.image-name

Broker image.

hivemq/hivemq-ce:2024.3

quarkus.hivemq.devservices.port

Fixed host port; random if unset.

(random)

quarkus.hivemq.devservices.shared

Reuse a running broker across apps/tests (dev mode).

true

quarkus.hivemq.devservices.service-name

quarkus-dev-service-mqtt label value used for discovery.

mqtt

quarkus.hivemq.devservices.container-env.*

Environment variables passed to the container.

—

Container sharing

When shared=true (the default, dev mode only), Quarkus looks for a running container labelled quarkus-dev-service-mqtt=<service-name> before starting a new one. If a matching container is found it is reused, so multiple applications can share a single broker. Set a distinct service-name when you need several independent shared brokers.