Installation

TinyMQ ships as a single static binary and an ultra-minimal Docker image (~13 MB). There are no configuration files, no runtimes to install, and no environment bootstrapping required.

Option 1: Docker (Recommended)

From GitHub Container Registry (GHCR)

docker pull ghcr.io/x-name15/tinymq:latest

docker run -d \
  --name tinymq \
  -p 7800:7800 \
  -p 1883:1883 \
  -v $(pwd)/data:/home/tinymq/data \
  ghcr.io/x-name15/tinymq:latest

Volume Mount Permissions

TinyMQ runs as an unprivileged user (UID 10001). If you are bind-mounting a local directory instead of a Docker volume, ensure the directory has the correct ownership: sudo chown -R 10001:10001 $(pwd)/data

For more advanced Docker configurations (TLS, networks), see the Docker Deployment Guide.

Option 2: Docker Compose

For homelab or production-like environments, docker-compose is the recommended setup. This configuration includes a healthcheck.

Create a docker-compose.yml file:

services:
  tinymq:
    image: ghcr.io/x-name15/tinymq:latest
    container_name: tinymq
    restart: unless-stopped
    ports:
      - "7800:7800"  # HTTP/WS
      - "1883:1883"  # MQTT
    volumes:
      - tinymq_data:/home/tinymq/data
    environment:
      - PORT=7800
      - TINYMQ_MAX_MESSAGES=100000
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:7800/healthz || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  tinymq_data:

Start the stack:

docker compose up -d

📦 Downloads (Broker Server + CLI Bundle)

Operating System	Download Archive
Windows (x64)	`tinymq-Checking version...-windows-amd64.zip`
Linux (x64)	`tinymq-Checking version...-linux-amd64.tar.gz`
Linux (ARM64)	`tinymq-Checking version...-linux-arm64.tar.gz`
macOS (Intel)	`tinymq-Checking version...-darwin-amd64.tar.gz`
macOS (Apple Silicon)	`tinymq-Checking version...-darwin-arm64.tar.gz`

Docker Images (multi‑arch: amd64 + arm64):

GHCR: docker pull ghcr.io/x-name15/tinymq:Checking version...
Docker Hub: docker pull flez71/tinymq:Checking version...

Option 4: Build from Source

Requires Go 1.25+.

git clone https://github.com/x-name15/tinymq.git
cd tinymq

# Build the broker
make build

# Run
./bin/tinymq

Environment Variables Configuration

TinyMQ is entirely configured via environment variables.

Broker Core

Variable	Default	Description
`PORT`	`7800`	HTTP listening port
`TINYMQ_FSYNC`	`false`	Force disk sync after every write (slows down writes but guarantees durability)
`TINYMQ_COMPACT_INTERVAL`	`10m`	Background WAL compaction interval
`TINYMQ_DEFAULT_POLICY`	`reject`	Queue overflow policy (`reject` or `drop-oldest`)
`TINYMQ_MAX_MESSAGES`	`100000`	Max messages per topic held in RAM
`TINYMQ_MAX_TOPICS`	`10000`	Max unique topics (DoS protection)
`TINYMQ_API_KEY`	(empty)	Global Bearer token for API authentication
`TINYMQ_RATE_LIMIT`	`0`	Per-IP request limit per second (0 = disabled)
`TINYMQ_TRUST_PROXY_HEADERS`	`false`	Trust `X-Real-IP` or `X-Forwarded-For` from reverse proxies for rate limiting
`TINYMQ_TLS_CERT`	(empty)	Path to TLS certificate for native HTTPS
`TINYMQ_TLS_KEY`	(empty)	Path to TLS private key

Transports

Variable	Default	Description
`TINYMQ_MQTT_PORT`	`1883`	TCP port for the MQTT v3.1.1 gateway
`TINYMQ_MQTT_DISABLE`	`false`	Set to `true` to completely disable MQTT
`TINYMQ_NATS_PORT`	(empty)	TCP port for NATS Gateway (e.g., `4222`)

Clustering

Variable	Default	Description
`TINYMQ_CLUSTER_ADDR`	(empty)	TCP bind address for clustering (e.g. `0.0.0.0:7901`)
`TINYMQ_CLUSTER_SELF`	(empty)	Advertised identity to peers (Required in Kubernetes)
`TINYMQ_CLUSTER_NODES`	(empty)	Comma-separated list of peer addresses
`TINYMQ_CLUSTER_SECRET`	(empty)	HMAC-SHA256 secret for securing cluster traffic
`TINYMQ_CLUSTER_HTTP_ADVERTISE`	(empty)	The HTTP address followers use to proxy to the leader
`TINYMQ_CLUSTER_REPLICATE_TIMEOUT`	`500ms`	Use `2s` or `3s` in Kubernetes due to DNS latency
`TINYMQ_CLUSTER_LEADER`	`false`	Force static leadership (disables automatic elections)
`TINYMQ_CLUSTER_ALLOW_INSECURE`	`false`	For testing, bypasses HMAC secret requirement if empty

CLI Configuration

Variable	Default	Description
`TINYMQ_URL`	`http://127.0.0.1:7800`	Target broker URL used automatically by the `tmq` CLI

Verifying the Installation

Check broker stats:

curl http://localhost:7800/api/stats

Access the dashboard: http://localhost:7800/dashboard

What's Next?

Kubernetes Deployment → — Learn how to deploy TinyMQ in a K8s StatefulSet
Core Concepts: Storage & WAL → — Understand how messages survive restarts
CLI & Dashboard → — Use tmq to interact with the broker

Option 1: Docker (Recommended)​

From GitHub Container Registry (GHCR)​

Option 2: Docker Compose​

📦 Downloads (Broker Server + CLI Bundle)​

Option 4: Build from Source​

Environment Variables Configuration​

Broker Core​

Transports​

Clustering​

CLI Configuration​

Verifying the Installation​

What's Next?​