Skip to content

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:

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:
  1. The REST API is available at http://localhost:9091.
  2. Keep the queues on disk, so they survive a restart. Without it, queues only live in memory.
  3. Enables /openapi/v1.json and the Scalar UI at /scalar.
  4. The dashboard can show several servers: DASHBOARD__QUEUES__1__… adds the next one.
docker compose -f deploy/docker/docker-compose.yml up -d
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:

AppHost/Program.cs
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();
  1. Persists the queues to %LOCALAPPDATA%/messagequeue-aspire. Use WithVolumePersistance() for a volume.
  2. Shows all queues of the server under the name mq.
  3. 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__…):

_config/dashboard.json
{
  "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):

dotnet tool install -g MessageQueueNET.Cmd
mqnet http://localhost:9091 -c shell

See Command line tools.