Server Setup

This guide describes various ways to configure and run the VibeMQ server.

For running the broker in Docker with environment-based configuration, see Docker. For an optional Web dashboard (health, metrics, queues), see Web UI Dashboard.

Basic Configuration 

Minimal Configuration 

Simplest way to start server:

using VibeMQ.Server;

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .Build();

await broker.RunAsync(CancellationToken.None);

This code will start server on port 2925 without authentication and with default settings.

Advanced Configuration 

using Microsoft.Extensions.Logging;
using VibeMQ.Server;
using VibeMQ.Enums;

using var loggerFactory = LoggerFactory.Create(builder => {
    builder.SetMinimumLevel(LogLevel.Information).AddConsole();
});

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthentication("my-secret-token")
    .UseMaxConnections(1000)
    .UseMaxMessageSize(1_048_576)  // 1 MB
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 10_000;
        options.EnableAutoCreate = true;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 50;
        options.MaxMessagesPerClientPerSecond = 1000;
    })
    .ConfigureHealthChecks(options => {
        options.Enabled = true;
        options.Port = 2926;
    })
    .UseTls(options => {
        options.Enabled = false;  // Enable for production
        options.CertificatePath = "/path/to/cert.pfx";
        options.CertificatePassword = "cert-password";
    })
    .UseLoggerFactory(loggerFactory)
    .Build();

await broker.RunAsync(CancellationToken.None);

Configuration Parameters 

Basic Parameters 

Parameter	Default	Description
`Port`	2925	TCP port for client connections
`MaxConnections`	1000	Maximum number of connections
`MaxMessageSize`	1 MB	Maximum message size
`EnableAuthentication`	false	Enable legacy token authentication
`AuthToken`	null	Token for legacy authentication (deprecated)
`Authorization`	null	Enable username/password auth with per-queue ACL (see Authorization)

Default Queue Settings 

Parameter	Default	Description
`DefaultDeliveryMode`	RoundRobin	Default delivery mode
`MaxQueueSize`	10,000	Maximum queue size
`EnableAutoCreate`	true	Automatic queue creation

Per-queue options (MessageTtl, EnableDeadLetterQueue, MaxRetryAttempts, OverflowStrategy) are set via QueueOptions when creating a queue with client.CreateQueueAsync(name, options); see Client Usage.

Rate Limiting 

Parameter	Default	Description
`Enabled`	true	Enable rate limiting
`MaxConnectionsPerIpPerWindow`	20	Max connections from IP per window
`ConnectionWindow`	60 sec	Time window (TimeSpan)
`MaxMessagesPerClientPerSecond`	1000	Max messages from client per sec

TLS/SSL Settings 

Parameter	Default	Description
`Enabled`	false	Enable TLS
`CertificatePath`	null	Path to PFX certificate
`CertificatePassword`	null	Certificate password

Health Check Settings 

Parameter	Default	Description
`Enabled`	true	Enable health check server
`Port`	2926	HTTP port for health checks

Delivery Modes 

Round-robin 

Each message is delivered to one subscriber cyclically:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
});

Usage:

Task processing by multiple workers
Load balancing
Task queues

Fan-out with Acknowledgment 

Message delivered to all subscribers with delivery guarantee:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.FanOutWithAck;
});

Usage:

Notification broadcasting
Data replication
Audit and logging

Fan-out without Acknowledgment 

Message delivered to all subscribers without acknowledgment:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.FanOutWithoutAck;
});

Usage:

Broadcast messages
Real-time updates
Data streaming

Priority-based 

Delivery by message priority:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.PriorityBased;
});

Priorities:

Critical — critical (delivered first)
High — high
Normal — normal (default)
Low — low (delivered last)

Publishing example:

using VibeMQ.Enums;

await client.PublishAsync("alerts", message, new Dictionary<string, string> {
    ["priority"] = MessagePriority.Critical.ToString()
});

Overflow Strategies 

DropOldest 

Remove oldest message on overflow:

// Set via QueueOptions when creating queue: client.CreateQueueAsync("q", new QueueOptions { OverflowStrategy = OverflowStrategy.DropOldest });

When to use:

Fresh data is important
Old messages lose relevance

DropNewest 

Reject new message:

.ConfigureQueues(options => {
    options.OverflowStrategy = OverflowStrategy.DropNewest;
});

When to use:

All existing messages are important
New messages can wait

BlockPublisher 

Block publisher until space is available:

// Set via QueueOptions when creating queue: client.CreateQueueAsync("q", new QueueOptions { OverflowStrategy = OverflowStrategy.BlockPublisher });

When to use:

Message loss is unacceptable
Publisher can wait

RedirectToDlq 

Redirect to Dead Letter Queue:

// Set via QueueOptions when creating queue: client.CreateQueueAsync("q", new QueueOptions { OverflowStrategy = OverflowStrategy.RedirectToDlq, EnableDeadLetterQueue = true, DeadLetterQueueName = "dlq" });

When to use:

All messages must be preserved
Subsequent processing planned

Dead Letter Queue 

DLQ Configuration:

// Set via QueueOptions when creating queue: client.CreateQueueAsync("q", new QueueOptions { EnableDeadLetterQueue = true, DeadLetterQueueName = "dead-letters", MaxRetryAttempts = 3 });

Reasons for DLQ:

Exceeded maximum delivery attempts
Message TTL expired
Deserialization error
Exception in handler

Getting messages from DLQ: DLQ messages are persisted by the broker’s storage provider. To consume them you can subscribe to the Dead Letter Queue by name (if the broker exposes it as a queue) or use a custom component that has access to the storage provider’s GetDeadLetteredMessagesAsync API. See Persistence & Storage for storage provider details.

Authorization (Username/Password + ACL)

The recommended authentication mode for production. Uses BCrypt-hashed passwords and per-queue ACL stored in a dedicated SQLite database:

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthorization(o => {
        o.SuperuserUsername = "admin";
        o.SuperuserPassword = Environment.GetEnvironmentVariable("VIBEMQ_ADMIN_PASS");
        o.DatabasePath = "/var/lib/vibemq/auth.db";
    })
    .Build();

On client:

var client = await VibeMQClient.ConnectAsync(
    "localhost",
    2925,
    new ClientOptions {
        Username = "alice",
        Password = "alice-secret"
    }
);

See Authorization for full details (users, ACL patterns, admin commands).

Legacy Token Authentication 

Enabling Authentication:

On client:

var client = await VibeMQClient.ConnectAsync(
    "localhost",
    2925,
    new ClientOptions {
        AuthToken = "my-secret-token"
    }
);

Warning

Use complex tokens in production (minimum 32 characters). Store tokens securely (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault).

TLS/SSL Encryption 

TLS Configuration:

.UseTls(options => {
    options.Enabled = true;
    options.CertificatePath = "/path/to/cert.pfx";
    options.CertificatePassword = "cert-password";
})

Creating self-signed certificate (for tests):

dotnet dev-certs https -ep vibemq.pfx -p cert-password
dotnet dev-certs https --trust

On client:

var client = await VibeMQClient.ConnectAsync(
    "localhost",
    2925,
    new ClientOptions {
        UseTls = true,
        // Tests only!
        SkipCertificateValidation = true
    }
);

Warning

Do not use SkipCertificateValidation = true in production!

Starting and Stopping 

Starting Server 

Async start:

await broker.RunAsync(cancellationToken);

Start with signal handling:

var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => {
    e.Cancel = true;
    cts.Cancel();
};

await broker.RunAsync(cts.Token);

Stopping Server 

Graceful stop:

await broker.StopAsync(cancellationToken);

Resource cleanup:

await broker.DisposeAsync();

Using statement:

await using var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .Build();

await broker.RunAsync(cancellationToken);
// DisposeAsync called automatically

Logging 

Logging Configuration:

using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(builder => {
    builder
        .SetMinimumLevel(LogLevel.Debug)
        .AddConsole()
        .AddDebug()
        .AddFile("logs/vibemq-.log");  // Requires Microsoft.Extensions.Logging.File package
});

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseLoggerFactory(loggerFactory)
    .Build();

Log levels:

Trace — detailed debugging
Debug — debug information
Information — informational messages
Warning — warnings
Error — errors
Critical — critical errors

Configuration Examples 

Minimal Server for Development 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .Build();

await broker.RunAsync(CancellationToken.None);

Production Server 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthentication(Environment.GetEnvironmentVariable("VIBEMQ_TOKEN"))
    .UseMaxConnections(5000)
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 100_000;
        options.EnableAutoCreate = true;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 50;
        options.MaxMessagesPerClientPerSecond = 5000;
    })
    .UseTls(options => {
        options.Enabled = true;
        options.CertificatePath = "/etc/ssl/vibemq.pfx";
        options.CertificatePassword = Environment.GetEnvironmentVariable("CERT_PASSWORD");
    })
    .UseLoggerFactory(loggerFactory)
    .Build();

Microservices Server 

var broker = BrokerBuilder.Create()
    .UsePort(2925)
    .UseAuthentication("microservice-token")
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.FanOutWithAck;
        options.EnableAutoCreate = true;
        options.MaxQueueSize = 10_000;
    })
    .ConfigureHealthChecks(options => {
        options.Enabled = true;
        options.Port = 2926;
    })
    .Build();

IoT Server 

var broker = BrokerBuilder.Create()
    .UsePort(8883)  // Standard MQTT port
    .UseAuthentication("iot-token")
    .UseMaxConnections(10000)
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 1000;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 500;
        options.MaxMessagesPerClientPerSecond = 100;  // Limit for devices
    })
    .Build();

Next Steps 

Client Usage — client usage
Configuration — detailed configuration
Monitoring — monitoring and health checks
DI Integration — DI integration