Docker Deployment

TinyMQ is compiled into an ultra-lean scratch Docker image. The final image size is roughly ~13 MB and contains 0 CVEs, making it incredibly secure and fast to pull.

Image Registries

TinyMQ is automatically published to both Docker Hub and GitHub Container Registry (GHCR) for both linux/amd64 and linux/arm64.

• Docker Hub: flez71/tinymq:latest
• GHCR: ghcr.io/x-name15/tinymq:latest

Quick Start (Docker Run)

docker run -d \
  --name tinymq \
  -p 7800:7800 \
  -v tinymq_data:/home/tinymq/data \
  ghcr.io/x-name15/tinymq:latest

Exposed Ports

Port	Protocol	Purpose
7800	TCP	HTTP REST API, WebSocket, SSE, Dashboard
1883	TCP	MQTT v3.1.1 Gateway
7901	TCP	Internal P2P Cluster communication
4222	TCP	NATS Gateway (Must be explicitly enabled)

Docker Compose

For most homelab and production deployments, docker-compose is recommended.

services:
  tinymq:
    image: ghcr.io/x-name15/tinymq:latest
    container_name: tinymq
    restart: unless-stopped
    ports:
      - "7800:7800"
      - "1883:1883"
      # - "4222:4222" # NATS Gateway
      # - "7901:7901" # Cluster Port
    volumes:
      - tinymq_data:/home/tinymq/data
    environment:
      - PORT=7800
      - TINYMQ_MAX_MESSAGES=100000
      # - TINYMQ_API_KEY=your_secret_key
      # - TINYMQ_NATS_PORT=4222
    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:

Volume Permissions (UID 10001)

For security reasons, TinyMQ does not run as root. The container creates and uses an unprivileged user with UID 10001 and GID 10001.

If you bind-mount a host directory instead of using a Docker named volume, you must ensure the directory is owned by UID 10001:

mkdir -p /path/to/host/data
sudo chown -R 10001:10001 /path/to/host/data

docker run -v /path/to/host/data:/home/tinymq/data ...

TLS (HTTPS) Support

You can enable native TLS for the HTTP server by mounting your certificates and pointing the environment variables to them:

    volumes:
      - ./certs:/certs:ro
    environment:
      - TINYMQ_TLS_CERT=/certs/fullchain.pem
      - TINYMQ_TLS_KEY=/certs/privkey.pem