Installation¶
MessageQueue.NET consists of two web applications:
- MessageQueueNET: the REST API (the actual message queue)
- MessageQueueNET.Blazor: the dashboard (optional)
Both run as Docker containers, standalone (dotnet MessageQueueNET.dll), behind IIS or as resources in an
Aspire application.
Docker¶
The images are published to the GitHub Container Registry. They run as the non-root user app on port 8080.
Tags: X.Y.Z, X.Y and latest (preview versions only get their version tag).
The repository contains a complete example in
deploy/docker/docker-compose.yml:
services:
messagequeue:
image: ghcr.io/jugstalt/messagequeue-net:${MQ_TAG:-latest}
ports:
- "9091:8080" # (1)!
environment:
MESSAGEQUEUE__PERSIST__TYPE: filesystem # (2)!
MESSAGEQUEUE__PERSIST__ROOTPATH: /home/app/messagequeue/persist
OPENAPIUI: "true" # (3)!
volumes:
- messagequeue-data:/home/app/messagequeue
restart: unless-stopped
dashboard:
image: ghcr.io/jugstalt/messagequeue-net-dashboard:${MQ_TAG:-latest}
ports:
- "9090:8080"
environment:
DASHBOARD__QUEUES__0__NAME: dev # (4)!
DASHBOARD__QUEUES__0__URL: http://messagequeue:8080
depends_on:
- messagequeue
restart: unless-stopped
volumes:
messagequeue-data:
- The REST API is available at
http://localhost:9091. - Keep the queues on disk, so they survive a restart. Without it, queues only live in memory.
- Enables
/openapi/v1.jsonand the Scalar UI at/scalar. - The dashboard can show several servers:
DASHBOARD__QUEUES__1__…adds the next one.
docker run -d -p 9091:8080 -v mq-data:/home/app/messagequeue \
-e MESSAGEQUEUE__PERSIST__TYPE=filesystem \
-e MESSAGEQUEUE__PERSIST__ROOTPATH=/home/app/messagequeue/persist \
ghcr.io/jugstalt/messagequeue-net
docker run -d -p 9090:8080 \
-e DASHBOARD__QUEUES__0__NAME=dev \
-e DASHBOARD__QUEUES__0__URL=http://host.docker.internal:9091 \
ghcr.io/jugstalt/messagequeue-net-dashboard
Persistence
Persisted data belongs in /home/app/messagequeue. Mount a volume there, otherwise the queues are lost
when the container is recreated.
Aspire¶
The NuGet package MessageQueueNET.Aspire.Hosting
adds the server and the dashboard as container resources to an Aspire AppHost:
var builder = DistributedApplication.CreateBuilder(args);
var mq = builder
.AddMessageQueueNET("messagequeue")
.WithBindMountPersistance() // (1)!
.Build();
builder
.AddDashboardForMessageQueueNET("messagequeue-dashboard")
.ConnectToMessageQueue(mq, "mq") // (2)!
.ConnectToMessageQueue(mq, "mail", "mail*") // (3)!
.WithMaxPollingSeconds(5)
.Build();
builder.Build().Run();
- Persists the queues to
%LOCALAPPDATA%/messagequeue-aspire. UseWithVolumePersistance()for a volume. - Shows all queues of the server under the name
mq. - A second view on the same server, filtered to the queues
mail*.
AddMessageQueueNET and AddDashboardForMessageQueueNET accept optional httpPort and imageTag arguments.
ZIP packages¶
Every GitHub release contains ZIP packages for win-x64
and linux-x64. They require the ASP.NET Core 10 runtime.
<version>/
├── api/app/ # MessageQueueNET (REST API)
├── dashboard/app/ # MessageQueueNET.Blazor (dashboard)
├── cmd/ # MessageQueueNET.Cmd, MessageQueueNET.Processor
├── start-messagequeue(.bat|.sh) # API on http://localhost:9091
└── start-messagequeue-dashboard(.bat|.sh) # dashboard on http://localhost:9090
To run the API in IIS, point a website to api/app (with the
ASP.NET Core Hosting Bundle installed).
Updates
Put your settings into _config/message-queue.json (API) and _config/dashboard.json (dashboard).
To update, copy everything except the _config folder over the existing installation.
Dashboard¶
The dashboard reads the section Dashboard from appsettings.json, _config/dashboard.json or environment
variables (DASHBOARD__…):
{
"Dashboard": {
"Queues": [
{ "Name": "production", "Url": "https://dashboard:secret@mq.example.com" },
{ "Name": "mail", "Url": "https://dashboard:secret@mq.example.com", "Filter": "mail.*" }
],
"MaxPollingSeconds": 10
}
}
| Setting | Description |
|---|---|
Queues[].Name |
Display name of the server |
Queues[].Url |
URL of the REST API, credentials in URL format (https://clientId:secret@host) |
Queues[].Filter |
Queue name pattern (default: *) |
MaxPollingSeconds |
Maximum long polling time of the dashboard requests |
Tip
Give the dashboard a client with the read role. It needs write or admin only to create, suspend
or delete queues from the UI. See Authorization.
OpenAPI and Scalar¶
In the Development environment, or if openApiUI is true (environment variable OPENAPIUI), the API
description is available at /openapi/v1.json and an interactive UI at /scalar.
.NET tool¶
The command line client is also available as a .NET tool (requires the .NET 10 runtime):
See Command line tools.