Mosquitto’yu Docker’da Çalıştırma (docker run ve docker-compose)

Docker, kullanıp atılabilen ve tekrarlanabilir bir MQTT broker’ı edinmenin en hızlı yoludur. Resmi eclipse-mosquitto imajı küçüktür ve iyi bakımlıdır; ancak varsayılan ayarları neredeyse herkesi ilk seferde şaşırtır: bir config dosyası olmadan container’ın dışından bağlanamazsınız. Bu rehber, Mosquitto’yu Docker’da doğru şekilde kurar — kalıcı volume’lar, TCP ve WebSocket portları ve parola tabanlı kimlik doğrulama ile.

1. Klasör yapısını oluşturun

İmaj, /mosquitto altında üç dizin bekler. Bunları host üzerinde aynen oluşturun:

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

2. Minimal bir mosquitto.conf yazın

Mosquitto 2.x, hiçbir listener yapılandırılmadığında yalnızca localhost’u dinler — bir container içinde bu, kimsenin ona erişemeyeceği anlamına gelir. Bu config, MQTT’yi 1883’te ve WebSocket’leri 9001’de açar:

# 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

TLS, ACL veya bridge ayarları mı istiyorsunuz? mosquitto.conf oluşturucu bir formdan geçerli bir dosya üretir; kurulum rehberi ise local-only modunu daha ayrıntılı açıklar.

3. docker run ile başlatın

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

Ana sürüm etiketini sabitlemek (eclipse-mosquitto:2) sürpriz yükseltmeleri önler. Log’ları docker logs -f mosquitto ile kontrol edin; Opening ipv4 listen socket on port 1883 satırını ve 9001 için bir websockets satırını görmelisiniz.

4. Ya da Docker Compose kullanın

Hızlı bir testin ötesindeki her şey için bir Compose dosyasını versiyon kontrolünde tutmak daha kolaydır:

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

Aynı Compose projesindeki diğer servisler (Node-RED, Home Assistant, uygulamanız) broker’a servis adıyla erişir: mqtt://mosquitto:1883. Host’a yalnızca Docker dışındaki bir şeyin gerçekten ihtiyaç duyduğu portları açın.

5. docker exec ile bir parola dosyası ekleyin

Anonim erişim bir dakikalık test için uygundur, daha uzun hiçbir şey için asla. İmajla birlikte gelen mosquitto_passwd ile bir kullanıcı oluşturun:

# -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

Ardından config’i anonim erişimden parola doğrulamasına geçirin:

allow_anonymous false
password_file /mosquitto/config/passwd

docker restart mosquitto

ACL’ler ve TLS de aynı şekilde çalışır — dosyalar config volume’una konur. Bkz. Mosquitto’yu parolalar, ACL’ler ve TLS ile güvenli hâle getirme.

6. Container’ı test edin

Host üzerinden (Mosquitto client’ları kuruluysa):

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'

Host’ta client yok mu? Container içindekileri kullanın:

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

9001’deki WebSocket listener’ı, tarayıcı client’larının kullandığı listener’dır (ws://<host>:9001). HTTPS üzerinden yüklenen bir sayfanın yalnızca wss:// bağlantıları açabileceğini unutmayın; bu nedenle yerel bir broker’ı barındırılan bir web client’ından test etmek genellikle 9001 portunun önünde TLS gerektirir — ayrıntılar WebSocket üzerinden MQTT yazısında. Çalışan bir gidiş-dönüşün tarayıcıda nasıl göründüğünü görmek için önce herkese açık bir broker deneyin:

Online MQTT istemcisinde deneyin

Container sorunlarını giderme

Bunların dışındaki CONNACK kodları için MQTT reason code’ları başvurusu ve bağlantı hataları rehberi broker’ın size ne söylediğini açıklar.

İmajı güncelleme

Config, veri ve log’lar host üzerinde durduğu için yükseltme yalnızca daha yeni bir imajı çekip container’ı yeniden oluşturmaktan ibarettir. data volume’u korunduğu sürece retained mesajlar ve kalıcı oturumlar korunur:

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

Düz docker run ile imajı çekin, ardından docker rm -f mosquitto çalıştırıp aynı docker run komutunu yeniden çalıştırın. Bu komutu küçük bir shell script’inde tutmak (veya Compose’a geçmek) sizi volume flag’lerini yeniden yazmaktan kurtarır.

Production ipuçları

• Kesin bir imaj etiketi sabitleyin ve bilinçli olarak yükseltin; büyük yükseltmelerden önce Mosquitto changelog’unu okuyun.
• data’yı bir volume üzerinde tutun; aksi hâlde container yeniden oluşturulduğunda retained mesajlar ve kalıcı oturumlar kaybolur.
• İnternete herhangi bir şey açmadan önce 8883’e (ve WebSocket listener’ına) TLS koyun — kurallar için MQTT portları yazısına bakın.
• Hata ayıklamak için docker exec üzerinden mosquitto -v çalıştırmak yerine docker logs mosquitto çıktısını okuyun — o komut container içinde ikinci bir broker başlatır ve "address already in use" hatasıyla başarısız olur.

Sıkça sorulan sorular