Installation

This guide describes various ways to install VibeMQ.

System Requirements

Minimum requirements:

  • OS: Windows, Linux, macOS

  • .NET 8.0 SDK or higher

  • RAM: 512 MB (1 GB+ recommended)

  • Disk space: 100 MB

For production:

  • .NET 8.0 Runtime or .NET 10.0

  • 2+ GB RAM

  • SSD for better performance

NuGet Installation

Basic Packages

To use VibeMQ in your project, add the required packages:

# Broker server (includes protocol and health check from Core)
dotnet add package VibeMQ.Server

# Client for connection
dotnet add package VibeMQ.Client

# Core (models, interfaces, protocol, health check server)
dotnet add package VibeMQ.Core

Dependency Injection Packages

For integration with Microsoft.Extensions.DependencyInjection:

# DI for server
dotnet add package VibeMQ.Server.DependencyInjection

# DI for client
dotnet add package VibeMQ.Client.DependencyInjection

All Packages at Once

For quick addition of all components:

dotnet add package VibeMQ.Server
dotnet add package VibeMQ.Client
dotnet add package VibeMQ.Server.DependencyInjection
dotnet add package VibeMQ.Client.DependencyInjection

Docker Installation

VibeMQ can be run in a Docker container.

Dockerfile

Create a Dockerfile in your project:

FROM mcr.microsoft.com/dotnet/runtime:8.0 AS base
WORKDIR /app
EXPOSE 2925 2926

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["VibeMQ.Server.csproj", "."]
RUN dotnet restore
COPY . .
RUN dotnet build -c Release -o /app/build

FROM build AS publish
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "VibeMQ.Server.dll"]

Build and run:

docker pull bobsans/vibemq
docker run -p 2925:2925 -p 2926:2926 bobsans/vibemq

Docker Compose

For deployment with other services, create a docker-compose.yml:

version: '3.8'

services:
  vibemq:
    image: bobsans/vibemq:latest
    container_name: vibemq-broker
    ports:
      - "2925:2925"  # TCP port for clients
      - "2926:2926"  # HTTP port for health checks
    environment:
      - VIBEMQ__Port=2925
      - VibeMQ__Authorization__SuperuserPassword=my-secret-password
      - VIBEMQ__MaxConnections=1000
    volumes:
      - vibemq-data:/data
    restart: unless-stopped

  # Example client application
  my-app:
    image: my-app:latest
    depends_on:
      - vibemq
    environment:
      - VIBEMQCLIENT__Host=vibemq
      - VIBEMQCLIENT__Port=2925

volumes:
  vibemq-data:

Start:

docker-compose up -d

Installation from Source Code

Clone the Repository

git clone https://github.com/DarkBoy/VibeMQ.git
cd VibeMQ

Build the Project

# Build all projects
dotnet build -c Release

# Run tests
dotnet test

# Build a specific project
dotnet build src/VibeMQ.Server/VibeMQ.Server.csproj -c Release

Local Package Installation

To use a locally built version:

# Create local NuGet source
dotnet pack src/VibeMQ.Server -c Release -o ./nupkg
dotnet pack src/VibeMQ.Client -c Release -o ./nupkg

# Add local source
dotnet nuget add source ./nupkg --name LocalVibeMQ

# Install from local source
dotnet add package VibeMQ.Server --source LocalVibeMQ

Integration into Existing Projects

ASP.NET Core Application

For ASP.NET Core applications, use DI integration:

using VibeMQ.Server.DependencyInjection;
using VibeMQ.Client.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Add broker server
builder.Services.AddVibeMQBroker(options => {
    options.Port = 2925;
    options.Authorization = new AuthorizationOptions {
        SuperuserUsername = builder.Configuration["VibeMQ:Authorization:SuperuserUsername"] ?? "admin",
        SuperuserPassword = builder.Configuration["VibeMQ:Authorization:SuperuserPassword"] ?? "change-me"
    };
});

// Add client for sending messages
builder.Services.AddVibeMQClient(settings => {
    settings.Host = "localhost";
    settings.Port = 2925;
    settings.ClientOptions.Username = builder.Configuration["VibeMQ:Authorization:SuperuserUsername"];
    settings.ClientOptions.Password = builder.Configuration["VibeMQ:Authorization:SuperuserPassword"];
});

var app = builder.Build();
await app.RunAsync();

Worker Service

For background services (.NET Worker):

using VibeMQ.Client.DependencyInjection;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services => {
        services.AddHostedService<Worker>();
        services.AddVibeMQClient(settings => {
            settings.Host = "localhost";
            settings.Port = 2925;
        });
    })
    .Build();

await host.RunAsync();

Console Application

For console applications, use direct invocation:

using VibeMQ.Server;

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

await broker.RunAsync(CancellationToken.None);

Installation Verification

Server Verification

After starting the server, check the health endpoint:

curl http://localhost:2926/health/

Response should be:

{
  "status": "healthy",
  "active_connections": 0,
  "queue_count": 0,
  "memory_usage_mb": 128
}

Client Verification

Create a test script:

using VibeMQ.Client;

try {
    await using var client = await VibeMQClient.ConnectAsync("localhost", 2925);
    Console.WriteLine("✓ Connection successful!");
    Console.WriteLine($"Status: {(client.IsConnected ? "Connected" : "Disconnected")}");
} catch (Exception ex) {
    Console.WriteLine($"✗ Error: {ex.Message}");
}

Troubleshooting

Port Already in Use

Error: Address already in use

Solution: Change the port in configuration:

var broker = BrokerBuilder.Create()
    .UsePort(2927)  // Use a different port
    .Build();

Authentication Error

Error: Authentication failed

Solution: Make sure credentials match:

// Server
.UseAuthorization(options => {
    options.SuperuserUsername = "admin";
    options.SuperuserPassword = "my-password";
})

// Client
new ClientOptions { Username = "admin", Password = "my-password"  }

TLS/SSL Errors

Error: The remote certificate is invalid

Solution: For tests, disable validation:

new ClientOptions {
    UseTls = true,
    SkipCertificateValidation = true  // Only for tests!
}

For production, use valid certificates.

Next Steps