Instalación

TinyMQ se distribuye como un único binario estático y una imagen Docker ultraminimal (~13 MB). No hay archivos de configuración, ni runtimes que instalar, ni arranque de entorno requerido.

Opción 1: Docker (Recomendado)

Desde 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

Permisos de Montaje de Volumen

TinyMQ corre como un usuario sin privilegios (UID 10001). Si estás montando un directorio local en lugar de un volumen Docker, asegúrate de que el directorio tenga la propiedad correcta: sudo chown -R 10001:10001 $(pwd)/data

Para configuraciones Docker más avanzadas (TLS, redes), consulta la Guía de Despliegue con Docker.

Opción 2: Docker Compose

Para entornos homelab o similares a producción, docker-compose es la configuración recomendada. Esta configuración incluye un healthcheck.

Crea un archivo docker-compose.yml:

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:

Inicia el stack:

docker compose up -d

📦 Descargas (Servidor Broker + Bundle CLI)

Sistema Operativo	Archivo de Descarga
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`

Imágenes Docker (multi-arch: amd64 + arm64):

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

Opción 4: Compilar desde el Código Fuente

Requiere Go 1.25+.

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

# Compilar el broker
make build

# Ejecutar
./bin/tinymq

Configuración mediante Variables de Entorno

TinyMQ se configura íntegramente mediante variables de entorno.

Core del Broker

Variable	Valor por defecto	Descripción
`PORT`	`7800`	Puerto de escucha HTTP
`TINYMQ_FSYNC`	`false`	Fuerza la sincronización en disco tras cada escritura (ralentiza las escrituras pero garantiza la durabilidad)
`TINYMQ_COMPACT_INTERVAL`	`10m`	Intervalo de compactación WAL en segundo plano
`TINYMQ_DEFAULT_POLICY`	`reject`	Política de desbordamiento de queue (`reject` o `drop-oldest`)
`TINYMQ_MAX_MESSAGES`	`100000`	Máximo de mensajes por topic mantenidos en RAM
`TINYMQ_MAX_TOPICS`	`10000`	Máximo de topics únicos (protección DoS)
`TINYMQ_API_KEY`	(vacío)	Token Bearer global para autenticación API
`TINYMQ_RATE_LIMIT`	`0`	Límite de peticiones por segundo por IP (0 = desactivado)
`TINYMQ_TRUST_PROXY_HEADERS`	`false`	Confiar en `X-Real-IP` o `X-Forwarded-For` de reverse proxies para el rate limiting
`TINYMQ_TLS_CERT`	(vacío)	Ruta al certificado TLS para HTTPS nativo
`TINYMQ_TLS_KEY`	(vacío)	Ruta a la clave privada TLS

Transportes

Variable	Valor por defecto	Descripción
`TINYMQ_MQTT_PORT`	`1883`	Puerto TCP para el gateway MQTT v3.1.1
`TINYMQ_MQTT_DISABLE`	`false`	Establece a `true` para deshabilitar MQTT completamente
`TINYMQ_NATS_PORT`	(vacío)	Puerto TCP para el NATS Gateway (p. ej., `4222`)

Clustering

Variable	Valor por defecto	Descripción
`TINYMQ_CLUSTER_ADDR`	(vacío)	Dirección TCP de bind para clustering (p. ej., `0.0.0.0:7901`)
`TINYMQ_CLUSTER_SELF`	(vacío)	Identidad anunciada a los peers (obligatorio en Kubernetes)
`TINYMQ_CLUSTER_NODES`	(vacío)	Lista de direcciones de peers separadas por comas
`TINYMQ_CLUSTER_SECRET`	(vacío)	Secreto HMAC-SHA256 para asegurar el tráfico del cluster
`TINYMQ_CLUSTER_HTTP_ADVERTISE`	(vacío)	La dirección HTTP que usan los followers para hacer proxy al leader
`TINYMQ_CLUSTER_REPLICATE_TIMEOUT`	`500ms`	Usa `2s` o `3s` en Kubernetes por la latencia DNS
`TINYMQ_CLUSTER_LEADER`	`false`	Fuerza el liderazgo estático (desactiva las elecciones automáticas)
`TINYMQ_CLUSTER_ALLOW_INSECURE`	`false`	Para pruebas, omite el requisito de secreto HMAC si está vacío

Configuración CLI

Variable	Valor por defecto	Descripción
`TINYMQ_URL`	`http://127.0.0.1:7800`	URL del broker de destino usada automáticamente por la CLI `tmq`

Verificar la Instalación

Comprueba las estadísticas del broker:

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

Accede al dashboard: http://localhost:7800/dashboard

¿Qué Sigue?

Despliegue en Kubernetes → — Aprende a desplegar TinyMQ en un StatefulSet de K8s
Conceptos Core: Storage y WAL → — Entiende cómo los mensajes sobreviven a los reinicios
CLI y Dashboard → — Usa tmq para interactuar con el broker

Opción 1: Docker (Recomendado)​

Desde GitHub Container Registry (GHCR)​

Opción 2: Docker Compose​

📦 Descargas (Servidor Broker + Bundle CLI)​

Opción 4: Compilar desde el Código Fuente​

Configuración mediante Variables de Entorno​

Core del Broker​

Transportes​

Clustering​

Configuración CLI​

Verificar la Instalación​

¿Qué Sigue?​