05 Docker Deployment

Docker Deployment

MQTTProbe runs in Docker for easy team access. Official images are published to Docker Hub.

Quick Start (Localhost)

docker compose up -d

This starts:

• MQTTProbe on http://localhost:8080
• Mosquitto broker (optional) on port 1883

Open http://localhost:8080 in your browser and complete the first-run setup.

Production Deployment (TLS)

For production use with TLS encryption via Caddy reverse proxy:

1. Configure Environment

cp .env.example .env

Edit .env and set MQTTPROBE_HOST to your server's hostname or IP address:

MQTTPROBE_HOST=mqtt.example.com

2. Start Services

docker compose -f docker-compose.prod.yml up -d

This starts:

• MQTTProbe on internal port 8080
• Caddy reverse proxy on ports 80 and 443 (auto-TLS)
• Mosquitto broker with 4 listeners (1883, 8883, 9001, 9002)

3. Trust the Caddy Certificate (Optional)

Caddy uses a self-signed certificate by default. To trust it on client machines:

# Export the Caddy root CA
docker compose -f docker-compose.prod.yml cp caddy:/data/caddy/pki/authorities/local/root.crt caddy-root.crt

# Import into your OS trust store
# Windows: double-click and install to Trusted Root Certification Authorities
# macOS: security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain caddy-root.crt
# Linux: sudo cp caddy-root.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates

Docker Commands

# Start services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

# Rebuild after code changes
docker compose up --build -d

# Production start
docker compose -f docker-compose.prod.yml up -d

# Production rebuild
docker compose -f docker-compose.prod.yml up --build -d

Environment Variables

Variable	Default	Description
ASPNETCORE_HTTP_PORTS	8080	HTTP listen port (set in Dockerfile)
ASPNETCORE_ENVIRONMENT	Production	ASP.NET Core environment
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT	false	Enable ICU globalization
MQTTPROBE_HOST	localhost	Hostname for Caddy TLS certificate
AllowedHosts	localhost;127.0.0.1;[::1]	Allowed Host headers

Data Persistence

Configuration is stored in a Docker named volume mqttprobe-config mounted at /app/config:

/app/config/
├── appsettings.json    # Connections, auth, preferences, charts, emulators
├── secrets.dat         # Encrypted MQTT broker passwords
└── dp-keys/            # ASP.NET Data Protection keys

To back up your configuration:

docker compose cp mqttprobe:/app/config ./backup

Dockerfile Details

• Base image: mcr.microsoft.com/dotnet/aspnet:10.0-alpine3.23 (~130 MB)
• Non-root user: Runs as appuser (uid 1000)
• Health check: wget -q -O - http://127.0.0.1:8080/health (30s interval, 5s timeout, 10s start period)
• Multi-stage build: SDK image for build, runtime image for deployment

Reverse Proxy Configuration

Caddy (included)

The included Caddyfile (deploy/Caddyfile) handles TLS termination:

{ default_sni {$MQTTPROBE_HOST:localhost} }
{$MQTTPROBE_HOST:localhost} {
    tls internal
    reverse_proxy mqttprobe:8080
}

Using Your Own Reverse Proxy

If you use nginx, Traefik, or another reverse proxy:

1. Point the proxy to mqttprobe:8080
2. Set AllowedHosts environment variable to include your hostname
3. Forward the Host header and X-Forwarded-For headers

Example nginx config:

server {
    listen 443 ssl;
    server_name mqtt.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://mqttprobe:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /hubs {
        proxy_pass http://mqttprobe:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Note: The /hubs location requires WebSocket upgrade support for Blazor Server SignalR connections.

WSL2 / Docker Desktop

If you experience MQTTS (TLS, port 8883) connection failures on Docker Desktop for Windows, this is a known WSL2 MTU issue. The production compose file already includes:

networks:
  mqttprobe-net:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1400

Health Check

The /health endpoint returns 200 OK and is used by Docker's health check:

curl http://localhost:8080/health
# OK