Installation

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

---

Option 1: Docker (Recommended)

From Docker Hub

docker pull flez71/tinymq:latest

docker run -d \
  --name tinymq \
  -p 7800:7800 \
  -v $(pwd)/data:/root/data \
  flez71/tinymq:latest

From GitHub Container Registry (GHCR)

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

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

Volume Mount

The -v $(pwd)/data:/root/data flag mounts a local ./data directory into the container. This is where TinyMQ writes its WAL .log files. Without this mount, all data is lost when the container stops.

On Windows, replace $(pwd) with %cd% (CMD) or ${PWD} (PowerShell).

The broker starts immediately on port 7800. Verify it's running:

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

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

---

Option 2: Docker Compose

For homelab or production-like environments, use the provided Compose file. This is the recommended setup for persistent deployments.

Create a docker-compose.yml file:

services:
  tinymq:
    image: flez71/tinymq:latest
    environment:
      - PORT=7800
    ports:
      - "7800:7800"
    volumes:
      - ./data:/root/data
    restart: unless-stopped

Then start it:

docker compose up -d

To stop gracefully:

docker compose down

Graceful Shutdown

TinyMQ intercepts SIGTERM and SIGINT signals. When you run docker compose down or docker stop tinymq, the broker flushes all OS-level file buffers and closes file descriptors cleanly before exiting. No data corruption, no partial writes.

---

Option 3: Pre-Built Binaries

Download the broker binary directly from the GitHub Releases page.

Platform	Broker Binary	CLI Binary
Linux (amd64)	tinymq-linux-amd64	tmq-linux-amd64
macOS (Intel)	tinymq-darwin-amd64	tmq-darwin-amd64
macOS (Apple Silicon)	tinymq-darwin-arm64	tmq-darwin-arm64
Windows (amd64)	tinymq-windows-amd64.exe	tmq-windows-amd64.exe

Linux / macOS

# Download broker binary
curl -L https://github.com/x-name15/tinymq/releases/latest/download/tinymq-linux-amd64 \
  -o tinymq

# Make executable and install
chmod +x tinymq
sudo mv tinymq /usr/local/bin/tinymq

# Download and install CLI
curl -L https://github.com/x-name15/tinymq/releases/latest/download/tmq-linux-amd64 \
  -o tmq
chmod +x tmq
sudo mv tmq /usr/local/bin/tmq

Run the broker:

# Data is written to ./data by default
tinymq

The broker listens on port 7800 by default. Use the PORT environment variable to change it:

PORT=8080 tinymq

---

Option 4: Build from Source

Requires Go 1.23+.

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

# Build the broker
make build
# Binary lands at: ./bin/tinymq

# Build the CLI
go build -ldflags="-s -w" -o bin/tmq ./cmd/tmq

# Run
./bin/tinymq

Or build and run in a single step:

make run

---

Environment Variables

Variable	Default	Description
PORT	7800	HTTP listening port for the broker
TINYMQ_URL	http://localhost:7800	Used by the tmq CLI to locate the broker

---

Verifying the Installation

Once the broker is running, confirm it responds correctly:

# Check all active topics and stats
curl http://localhost:7800/api/stats

# Publish a test message
curl -X POST http://localhost:7800/publish/test \
  -H "Content-Type: application/json" \
  -d '{"hello": "TinyMQ"}'

# Consume that message back
curl http://localhost:7800/consume/test?auto_ack=true

Expected publish response:

{"status": "accepted", "topic": "test"}

Expected consume response:

{
  "id": "a1b2c3d4-...",
  "topic": "test",
  "payload": "eyJoZWxsbyI6ICJUaW55TVEifQ==",
  "timestamp": "2026-06-19T10:00:00Z",
  "retry_count": 0
}

Payload Encoding

Payloads are returned as Base64-encoded bytes. Decode with echo "eyJoZWxsbyI6ICJUaW55TVEifQ==" | base64 -d to get {"hello": "TinyMQ"}.

---

What's Next?

• Core Concepts: Storage & WAL → — Understand how messages survive restarts
• CLI & Dashboard → — Use tmq to interact with the broker and the web UI