# Dev Services for RabbitMQ

Dev Services for RabbitMQ automatically starts a RabbitMQ broker in dev mode and when running tests. So, you don’t have to start a broker manually. The application is configured automatically.

## Enabling / disabling Dev Services for RabbitMQ

Dev Services for RabbitMQ is automatically enabled unless:

- `quarkus.rabbitmq.devservices.enabled` is set to `false`

- the `rabbitmq-host` or `rabbitmq-port` is configured

- all the Reactive Messaging RabbitMQ channels have the `host` or `port` attributes set

Dev Services for RabbitMQ relies on Docker to start the broker. If your environment does not support Docker, you must start the broker manually, or connect to an already running broker. You can configure the broker access by using the `rabbitmq-host`, `rabbitmq-port`, `rabbitmq-username` and `rabbitmq-password` properties.

## Shared broker

Most of the time you want to share the broker between applications. Dev Services for RabbitMQ implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single broker.

| Dev Services for RabbitMQ starts the container with the `quarkus-dev-service-rabbitmq` label, which is used to identify the container.

If you need multiple (shared) brokers, you can configure the `quarkus.rabbitmq.devservices.service-name` attribute and indicate the broker name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is `rabbitmq`.

Sharing is enabled by default in dev mode, but disabled in test mode. You can disable the sharing with `quarkus.rabbitmq.devservices.shared=false`.

## Setting the port

By default, Dev Services for RabbitMQ picks a random port and configures the application. You can set the port by configuring the `quarkus.rabbitmq.devservices.port` property.

## Configuring the image

Dev Services for RabbitMQ uses official images available at https://hub.docker.com/_/rabbitmq. You can configure the image and version with the `quarkus.rabbitmq.devservices.image-name` property:

    quarkus.rabbitmq.devservices.image-name=rabbitmq:latest

## Access the management UI

By default, Dev Services for RabbitMQ use the official image with the `management` tag. This means you have the management plugin available. You can use the Dev UI to find the HTTP port randomly affected or configure a static one by using `quarkus.rabbitmq.devservices.http-port`.

## Predefined topology

Dev Services for RabbitMQ supports defining topology upon broker start. You can define Virtual Hosts, Exchanges, Queues, and Bindings through standard Quarkus configuration.

### Defining virtual hosts

RabbitMQ uses a default virtual host of `/`. To define additional RabbitMQ virtual hosts, provide the names of the virtual hosts in the `quarkus.rabbitmq.devservices.vhosts` key:

    quarkus.rabbitmq.devservices.vhosts=my-vhost-1,my-vhost-2

### Defining exchanges

To define a RabbitMQ exchange you provide the exchange’s name after the `quarkus.rabbitmq.devservices.exchanges` key, followed by one (or more) of the exchange’s properties:

    quarkus.rabbitmq.devservices.exchanges.my-exchange.type=topic            # defaults to 'direct'
    quarkus.rabbitmq.devservices.exchanges.my-exchange.auto-delete=false     # defaults to 'false'
    quarkus.rabbitmq.devservices.exchanges.my-exchange.durable=true          # defaults to 'false'
    quarkus.rabbitmq.devservices.exchanges.my-exchange.vhost=my-vhost        # defaults to '/'

Additionally, any additional arguments can be provided to the exchange’s definition by using the `arguments` key:

    quarkus.rabbitmq.devservices.exchanges.my-exchange.arguments.alternate-exchange=another-exchange

### Defining queues

To define a RabbitMQ queue you provide the queue’s name after the `quarkus.rabbitmq.devservices.queues` key, followed by one (or more) of the queue’s properties:

    quarkus.rabbitmq.devservices.queues.my-queue.auto-delete=false          # defaults to 'false'
    quarkus.rabbitmq.devservices.queues.my-queue.durable=true               # defaults to 'false'
    quarkus.rabbitmq.devservices.queues.my-queue.vhost=my-vhost             # defaults to '/'

Additionally, any additional arguments can be provided to the queue’s definition by using the `arguments` key:

    quarkus.rabbitmq.devservices.queues.my-queue.arguments.x-dead-letter-exchange=another-exchange

### Defining bindings

To define a RabbitMQ binding you provide the binding’s name after the `quarkus.rabbitmq.devservices.bindings` key, followed by one (or more) of the binding’s properties:

    quarkus.rabbitmq.devservices.bindings.a-binding.source=my-exchange      # defaults to name of binding
    quarkus.rabbitmq.devservices.bindings.a-binding.routing-key=some-key    # defaults to '#'
    quarkus.rabbitmq.devservices.bindings.a-binding.destination=my-queue    # defaults to name of binding
    quarkus.rabbitmq.devservices.bindings.a-binding.destination-type=queue  # defaults to 'queue'
    quarkus.rabbitmq.devservices.bindings.a-binding.vhost=my-vhost          # defaults to '/'

| The name of the binding is only used for the purposes of the Dev Services configuration and is not part of the binding defined in RabbitMQ.

Additionally, any additional arguments can be provided to the binding’s definition by using the `arguments` key:

    quarkus.rabbitmq.devservices.bindings.a-binding.arguments.non-std-option=value

## Configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property | Type | Default
--- | --- | ---
`quarkus.rabbitmq.devservices.enabled` If Dev Services for RabbitMQ has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. For RabbitMQ, Dev Services starts a broker unless `rabbitmq-host` or `rabbitmq-port` are set or if all the Reactive Messaging RabbitMQ channel are configured with `host` or `port`. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_ENABLED` | boolean |
`quarkus.rabbitmq.devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_PORT` | int |
`quarkus.rabbitmq.devservices.http-port` Optional fixed port for the RabbitMQ management plugin. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_HTTP_PORT` | int |
`quarkus.rabbitmq.devservices.image-name` The image to use. Note that only official RabbitMQ images are supported. Specifically, the image repository must end with `rabbitmq`. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_IMAGE_NAME` | string | `rabbitmq:3.12-management`
`quarkus.rabbitmq.devservices.shared` Indicates if the RabbitMQ broker managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for RabbitMQ starts a new container. The discovery uses the `quarkus-dev-service-rabbitmq` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_SHARED` | boolean | `true`
`quarkus.rabbitmq.devservices.service-name` The value of the `quarkus-dev-service-rabbitmq` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for RabbitMQ looks for a container with the `quarkus-dev-service-rabbitmq` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-rabbitmq` label set to the specified value. This property is used when you need multiple shared RabbitMQ brokers. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_SERVICE_NAME` | string | `rabbitmq`
`quarkus.rabbitmq.devservices.exchanges."exchange-name".type` Type of exchange: direct, topic, headers, fanout, etc. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_EXCHANGES__EXCHANGE_NAME__TYPE` | string | `direct`
`quarkus.rabbitmq.devservices.exchanges."exchange-name".auto-delete` Should the exchange be deleted when all queues are finished using it? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_EXCHANGES__EXCHANGE_NAME__AUTO_DELETE` | boolean | `false`
`quarkus.rabbitmq.devservices.exchanges."exchange-name".durable` Should the exchange remain after restarts? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_EXCHANGES__EXCHANGE_NAME__DURABLE` | boolean | `false`
`quarkus.rabbitmq.devservices.exchanges."exchange-name".vhost` What virtual host should the exchange be associated with? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_EXCHANGES__EXCHANGE_NAME__VHOST` | string | `/`
`quarkus.rabbitmq.devservices.exchanges."exchange-name".arguments."argument-name"` Extra arguments for the exchange definition. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_EXCHANGES__EXCHANGE_NAME__ARGUMENTS__ARGUMENT_NAME_` | Map<String,String> |
`quarkus.rabbitmq.devservices.queues."queue-name".auto-delete` Should the queue be deleted when all consumers are finished using it? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_QUEUES__QUEUE_NAME__AUTO_DELETE` | boolean | `false`
`quarkus.rabbitmq.devservices.queues."queue-name".durable` Should the queue remain after restarts? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_QUEUES__QUEUE_NAME__DURABLE` | boolean | `false`
`quarkus.rabbitmq.devservices.queues."queue-name".vhost` What virtual host should the queue be associated with? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_QUEUES__QUEUE_NAME__VHOST` | string | `/`
`quarkus.rabbitmq.devservices.queues."queue-name".arguments."argument-name"` Extra arguments for the queue definition. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_QUEUES__QUEUE_NAME__ARGUMENTS__ARGUMENT_NAME_` | Map<String,String> |
`quarkus.rabbitmq.devservices.bindings."binding-name".source` Source exchange to bind to. Defaults to name of binding instance. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_BINDINGS__BINDING_NAME__SOURCE` | string |
`quarkus.rabbitmq.devservices.bindings."binding-name".routing-key` Routing key specification for the source exchange. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_BINDINGS__BINDING_NAME__ROUTING_KEY` | string | `#`
`quarkus.rabbitmq.devservices.bindings."binding-name".destination` Destination exchange or queue to bind to. Defaults to name of binding instance. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_BINDINGS__BINDING_NAME__DESTINATION` | string |
`quarkus.rabbitmq.devservices.bindings."binding-name".destination-type` Destination type for binding: queue, exchange, etc. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_BINDINGS__BINDING_NAME__DESTINATION_TYPE` | string | `queue`
`quarkus.rabbitmq.devservices.bindings."binding-name".vhost` What virtual host should the binding be associated with? Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_BINDINGS__BINDING_NAME__VHOST` | string | `/`
`quarkus.rabbitmq.devservices.bindings."binding-name".arguments."argument-name"` Extra arguments for the binding definition. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_BINDINGS__BINDING_NAME__ARGUMENTS__ARGUMENT_NAME_` | Map<String,String> |
`quarkus.rabbitmq.devservices.vhosts` Virtual hosts that should be predefined after starting the RabbitMQ broker. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_VHOSTS` | list of string |
`quarkus.rabbitmq.devservices.container-env."environment-variable-name"` Environment variables that are passed to the container. Environment variable: `QUARKUS_RABBITMQ_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_` | Map<String,String> |