Panduan Instalasi MQTT Broker dengan Docker dan Cloudflare Tunnel

MQTT (Message Queuing Telemetry Transport) adalah protokol komunikasi ringan yang dirancang khusus untuk perangkat IoT (Internet of Things). Protokol ini bekerja dengan model publish/subscribe, di mana perangkat dapat mengirim (publish) dan menerima (subscribe) pesan melalui sebuah server perantara yang disebut broker.

Dalam panduan ini, kita akan menginstal Mosquitto sebagai MQTT broker menggunakan Docker di atas perangkat STB TV Box berbasis ARM64 yang menjalankan Armbian. Agar broker dapat diakses dari internet tanpa perlu membuka port router, kita akan menggunakan Cloudflare Tunnel sebagai jembatan yang aman.

Keunggulan pendekatan ini:

• Tidak perlu membuka port di router (tanpa port forwarding)
• Koneksi terenkripsi SSL/TLS otomatis dari Cloudflare
• Dapat diakses dari mana saja melalui internet
• Kompatibel dengan MQTT over WebSocket untuk kemudahan integrasi

Prasyarat

Sebelum memulai, pastikan perangkat sudah memenuhi syarat berikut:

Langkah 1: Membuat Struktur Folder

Langkah pertama adalah membuat folder yang akan menyimpan semua file konfigurasi, data, dan log dari Mosquitto. Kita menempatkannya di /opt/mqtt karena direktori /opt adalah lokasi standar untuk aplikasi tambahan di Linux, sehingga mudah dikelola dan tidak bercampur dengan sistem.

mkdir -p /opt/mqtt/config /opt/mqtt/data /opt/mqtt/log

Perintah ini membuat tiga subfolder sekaligus:

• /opt/mqtt/config — menyimpan file konfigurasi dan password
• /opt/mqtt/data — menyimpan data pesan yang di-persist
• /opt/mqtt/log — menyimpan file log aktivitas broker

Langkah 2: Membuat File Konfigurasi Mosquitto

Konfigurasi ini mendefinisikan dua listener: satu untuk MQTT biasa di port 1883 (digunakan secara lokal) dan satu untuk MQTT over WebSocket di port 9001 (yang akan diekspos ke internet melalui Cloudflare).

Kita memilih WebSocket untuk akses dari luar karena Cloudflare Tunnel mendukung protokol HTTP/WebSocket secara native, sehingga tidak perlu konfigurasi tambahan yang rumit seperti pada koneksi TCP biasa.

cat > /opt/mqtt/config/mosquitto.conf << 'EOF'
# Listener MQTT biasa (lokal saja)
listener 1883
protocol mqtt

# Listener WebSocket (untuk akses dari luar via Cloudflare)
listener 9001
protocol websockets

# Autentikasi - wajib agar tidak sembarang orang bisa konek
allow_anonymous false
password_file /mosquitto/config/passwd

# Simpan pesan agar tidak hilang saat restart
persistence true
persistence_location /mosquitto/data/

# Logging
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout
log_type all
EOF

Catatan: allow_anonymous false sangat penting untuk keamanan. Tanpa setting ini, siapa saja bisa terhubung ke broker MQTT kamu tanpa perlu password.

Langkah 3: Fix Permission Folder

Ini adalah langkah yang sering terlewat dan menjadi penyebab error paling umum. Container Mosquitto berjalan menggunakan user bernama mosquitto dengan UID 1883, bukan sebagai root. Jika folder dibuat oleh root, Mosquitto tidak akan memiliki izin untuk membaca dan menulis ke folder tersebut.

chown -R 1883:1883 /opt/mqtt/
chmod -R 755 /opt/mqtt/

Catatan: Jika langkah ini dilewati, Mosquitto akan gagal start dengan error: Unable to open pwfile dan Unable to open log file.

Langkah 4: Membuat File Password

Kita menggunakan tool mosquitto_passwd yang sudah tersedia di dalam image Docker Mosquitto, sehingga tidak perlu menginstall apapun di host.

Jalankan perintah berikut untuk membuat user admin:

docker run -it --rm \
  -v /opt/mqtt/config:/mosquitto/config \
  eclipse-mosquitto \
  mosquitto_passwd -c /mosquitto/config/passwd admin

Flag -c berarti create file baru. Masukkan password yang kuat saat diminta.

Jika ingin menambah user lain tanpa menghapus yang sudah ada, hilangkan flag -c:

docker run -it --rm \
  -v /opt/mqtt/config:/mosquitto/config \
  eclipse-mosquitto \
  mosquitto_passwd /mosquitto/config/passwd namauser

Setelah file password dibuat, perbaiki permission-nya:

chown 1883:1883 /opt/mqtt/config/passwd

Langkah 5: Menjalankan Container Mosquitto

Jalankan container dengan beberapa opsi penting:

• --restart unless-stopped — container akan otomatis restart jika server reboot
• -p 1883:1883 — expose port MQTT untuk akses lokal
• -p 9001:9001 — expose port WebSocket untuk digunakan Cloudflare

docker run -d \
  --name mosquitto \
  --restart unless-stopped \
  -p 1883:1883 \
  -p 9001:9001 \
  -v /opt/mqtt/config/mosquitto.conf:/mosquitto/config/mosquitto.conf \
  -v /opt/mqtt/config/passwd:/mosquitto/config/passwd \
  -v /opt/mqtt/data:/mosquitto/data \
  -v /opt/mqtt/log:/mosquitto/log \
  eclipse-mosquitto

Verifikasi container berjalan dengan baik:

docker ps
docker logs mosquitto

Jika berhasil, di log akan muncul:

mosquitto version 2.x.x starting
Opening ipv4 listen socket on port 1883.
Opening ipv4 listen socket on port 9001.
mosquitto version 2.x.x running

Langkah 6: Konfigurasi Cloudflare Tunnel

Konfigurasi ini bisa dilakukan langsung dari dashboard Cloudflare tanpa perlu menyentuh file apapun di server, selama tunnel sudah berjalan.

1. Buka dash.cloudflare.com dan login
2. Pilih domain kamu → Zero Trust → Networks → Tunnels
3. Klik tunnel yang sudah running → Edit
4. Pilih tab Public Hostname → Add a public hostname
5. Isi form berikut:

6. Klik Save hostname

Catatan: Gunakan Type HTTP (bukan TCP). WebSocket berjalan di atas HTTP, sehingga Cloudflare bisa meneruskan koneksi WebSocket dengan benar tanpa konfigurasi tambahan.

Verifikasi: Test Koneksi dari Browser

Untuk memastikan MQTT broker sudah bisa diakses dari internet, gunakan HiveMQ WebSocket Client di browser:

🔗 https://www.hivemq.com/demos/websocket-client/

Isi dengan parameter berikut:

Klik Connect. Jika status berubah menjadi Connected (lingkaran hijau), instalasi berhasil sempurna!

Troubleshooting Umum

Error: Unable to open pwfile

Penyebab: Permission folder tidak sesuai. File password tidak bisa dibaca oleh user mosquitto di dalam container.

Solusi:

chown -R 1883:1883 /opt/mqtt/
docker restart mosquitto

Error: Unable to open log file

Penyebab: Folder log tidak bisa ditulis oleh container.

Solusi: Sama dengan di atas, pastikan chown sudah dijalankan sebelum container distart.

Tidak bisa konek dari luar (timeout)

• Tunnel belum aktif — cek status di dashboard Cloudflare
• Type di Cloudflare salah — pastikan menggunakan HTTP bukan TCP
• Container Mosquitto tidak running — cek dengan docker ps

Penutup

Dengan mengikuti langkah-langkah di atas, kamu sudah berhasil menjalankan MQTT broker Mosquitto yang aman dan dapat diakses dari internet melalui Cloudflare Tunnel. Setup ini cocok digunakan sebagai backend untuk proyek smart home, monitoring sensor IoT, atau integrasi dengan platform seperti Home Assistant dan Node-RED.

Beberapa hal yang bisa dikembangkan selanjutnya:

• Integrasi dengan Home Assistant sebagai MQTT broker utama
• Menambahkan Node-RED untuk automasi alur data IoT
• Menghubungkan perangkat ESP8266/ESP32 ke broker ini
• Menambahkan monitoring dengan MQTT Explorer