Rodar o Mosquitto no Docker (docker run e docker-compose)

O Docker é a forma mais rápida de ter um broker MQTT descartável e reproduzível. A imagem oficial eclipse-mosquitto é pequena e bem mantida, mas seus padrões surpreendem quase todo mundo na primeira vez: sem um arquivo de configuração, você não consegue se conectar de fora do container. Este guia configura o Mosquitto no Docker do jeito certo — com volumes persistentes, portas TCP e WebSocket e autenticação por senha.

1. Crie a estrutura de pastas

A imagem espera três diretórios em /mosquitto. Replique-os no host:

mkdir -p mosquitto/config mosquitto/data mosquitto/log
touch mosquitto/config/mosquitto.conf

2. Escreva um mosquitto.conf mínimo

O Mosquitto 2.x só escuta no localhost quando nenhum listener está configurado — dentro de um container, isso significa que ninguém consegue alcançá-lo. Esta configuração abre MQTT na 1883 e WebSockets na 9001:

# MQTT over TCP
listener 1883
# MQTT over WebSockets
listener 9001
protocol websockets

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

# For a first test only — switched to a password file in step 5
allow_anonymous true

Quer TLS, ACLs ou configurações de bridge? O gerador de mosquitto.conf monta um arquivo válido a partir de um formulário, e o guia de instalação explica o modo somente local em mais detalhes.

3. Inicie com docker run

docker run -d --name mosquitto \
  --restart unless-stopped \
  -p 1883:1883 -p 9001:9001 \
  -v "$PWD/mosquitto/config:/mosquitto/config" \
  -v "$PWD/mosquitto/data:/mosquitto/data" \
  -v "$PWD/mosquitto/log:/mosquitto/log" \
  eclipse-mosquitto:2

Fixar a tag da versão principal (eclipse-mosquitto:2) evita upgrades inesperados. Confira os logs com docker logs -f mosquitto; você deve ver Opening ipv4 listen socket on port 1883 e uma linha de websockets para a 9001.

4. Ou use o Docker Compose

Para qualquer coisa além de um teste rápido, um arquivo Compose é mais fácil de manter no controle de versão:

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"   # MQTT
      - "9001:9001"   # MQTT over WebSockets
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

docker compose up -d
docker compose logs -f mosquitto

Outros serviços no mesmo projeto Compose (Node-RED, Home Assistant, sua aplicação) alcançam o broker pelo nome do serviço: mqtt://mosquitto:1883. Publique no host apenas as portas de que algo fora do Docker realmente precisa.

5. Adicione um arquivo de senhas via docker exec

Acesso anônimo serve para um minuto de teste, nunca para mais do que isso. Crie um usuário com o mosquitto_passwd, que já vem dentro da imagem:

# -c creates the file (overwrites it if it exists!) — use only for the first user
docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd alice

# add more users without -c
docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd bob

Depois, mude a configuração de acesso anônimo para autenticação por senha:

allow_anonymous false
password_file /mosquitto/config/passwd

docker restart mosquitto

ACLs e TLS funcionam do mesmo jeito — os arquivos vão no volume de configuração. Veja como proteger o Mosquitto com senhas, ACLs e TLS.

6. Teste o container

A partir do host (com os clientes do Mosquitto instalados):

mosquitto_sub -h localhost -p 1883 -u alice -P 'secret' -t 'demo/#' -v &
mosquitto_pub -h localhost -p 1883 -u alice -P 'secret' -t 'demo/hello' -m 'hi from docker'

Não tem os clientes no host? Use os que estão dentro do container:

docker exec -it mosquitto mosquitto_sub -h localhost -u alice -P 'secret' -t 'demo/#' -v

O listener WebSocket na 9001 é o que os clientes no navegador usam (ws://<host>:9001). Lembre que uma página carregada via HTTPS só pode abrir conexões wss://, então testar um broker local a partir de um cliente web hospedado geralmente exige TLS na frente da porta 9001 — mais em MQTT sobre WebSockets. Para ver como é uma ida e volta funcionando no navegador, experimente antes um broker público:

Teste no cliente MQTT online

Solução de problemas no container

Para códigos de CONNACK além desses, a referência de reason codes MQTT e o guia de erros de conexão explicam o que o broker está dizendo.

Atualizando a imagem

Como configuração, dados e logs ficam no host, atualizar é só baixar uma imagem mais nova e recriar o container. Mensagens retidas e sessões persistentes sobrevivem enquanto o volume data for mantido:

docker compose pull mosquitto
docker compose up -d mosquitto
docker compose logs --tail 20 mosquitto

Com docker run puro, baixe a imagem, rode docker rm -f mosquitto e execute o mesmo comando docker run de novo. Guardar esse comando em um pequeno script shell (ou migrar para o Compose) evita redigitar as flags de volume.

Dicas para produção

• Fixe uma tag exata da imagem e atualize de forma deliberada; leia o changelog do Mosquitto antes de upgrades de versão principal.
• Mantenha data em um volume; caso contrário, mensagens retidas e sessões persistentes somem quando o container é recriado.
• Coloque TLS na 8883 (e no listener WebSocket) antes de expor qualquer coisa na internet — veja portas MQTT para as convenções.
• Para depurar, leia docker logs mosquitto em vez de rodar mosquitto -v via docker exec — isso inicia um segundo broker dentro do container e falha com "address already in use".

Perguntas frequentes