Building a Containerized MQTT Gateway on Raspberry Pi

Part 1 – Creating a Containerized MQTT Foundation

In the world of the Internet of Things, there is a common misconception that every device should connect directly to the cloud. While this works for a single smart bulb in a living room, it is rarely the right design for professional, industrial, or scalable IoT systems.

In real deployments, dozens or even hundreds of devices generate data continuously. Sending all of this raw data directly to the internet is inefficient, expensive, and often unreliable. This is why modern IoT architectures use a local gateway — a small but powerful computer that sits close to the devices and manages communication, storage, and processing.

In this series, we are going to build such a gateway using a Raspberry Pi and containerized services. In this first part, we will create the most important building block of any IoT system: a local MQTT messaging hub running inside Docker.

High-level IoT gateway architecture. Multiple sensor nodes (ESP32, Pico W, and industrial sensors) send data to a local MQTT broker, which runs on a Raspberry Pi gateway and forwards the data to databases, dashboards, and cloud services.

If you want a slightly shorter version:

Figure 1 — Overall architecture of the Raspberry Pi–based Io

Direct-to-Cloud vs Gateway-Based IoT

For simple consumer devices like a smart plug or a Wi-Fi bulb, connecting directly to the cloud makes sense. The data volume is small, and the setup is simple.

In industrial and professional IoT systems, however:

• Many sensors send data continuously

• Networks may be unreliable

• Security is critical

• Cloud connectivity cannot be assumed

This is why devices first talk to a local gateway, and only the gateway communicates with the cloud when needed.

Comparison of direct-to-cloud and gateway-based IoT architectures. In simple consumer devices, sensors connect directly to the cloud, while in industrial systems, devices first communicate with a local gateway that manages data, security, and reliability before forwarding it to the cloud.

What an IoT Gateway Does

An IoT gateway sits between:

• Field devices (ESP32, Pico W, sensors)

• Higher-level systems (databases, dashboards, cloud)

It:

• Receives sensor data

• Buffers it locally

• Distributes it to applications

• Provides a secure entry point

To make this work, we need a fast, lightweight messaging system — MQTT.

Why MQTT?

MQTT is built for machine-to-machine communication. Compared to HTTP, it is:

• Lightweight

• Efficient

• Designed for unreliable networks

• Perfect for many small messages

It uses a publish–subscribe model where devices send data to a broker, and applications receive only what they subscribe to.

Our gateway will use MQTT as its central nervous system.

MQTT publish–subscribe flow. Devices publish data to the MQTT broker, and the gateway receives it, stores it in a database, and updates dashboards in real time.

Why Use Docker on the Gateway?

Instead of installing everything directly on Raspberry Pi OS, we will use Docker.

Docker allows us to:

• Run each service in isolation

• Upgrade or remove services safely

• Rebuild the gateway on another Pi easily

• Add more services later (databases, dashboards, AI)

Figure 3 — Raspberry Pi acting as a container host. Each box (MQTT, Database, Dashboard, Future AI) represents a separate Docker container running on the gateway.

This is how real IoT gateways are built.

Hands-On: Setting Up Docker and MQTT

We will now turn a Raspberry Pi into a real IoT gateway.

Step 1 – System Preparation

Update the system:

sudo apt update
sudo apt upgrade -y

(Optional but recommended)

sudo raspi-config

Enable SSH and set locale and timezone.

Step 2 – Install Docker

Install Docker using the official script:

curl -fsSL https://get.docker.com | sh

Verify Docker service:

sudo systemctl status docker

Expected: active (running)

Step 3 – Add User to Docker Group (Critical)

sudo usermod -aG docker $USER

This adds user pi to the Docker group.

Step 4 – Reboot (Must Not Be Skipped)

sudo reboot

Docker group changes only apply after login.

Step 5 – Verify Docker Permissions

groups

You must see docker.

docker ps

No errors should appear.

Step 6 – Create Gateway Project Folder

mkdir -p ~/projects/iot-gateway
cd ~/projects/iot-gateway

Step 7 – Create docker‑compose.yml

geany docker-compose.yml

Paste:

version: "3.8"
services:
  mqtt:
    image: eclipse-mosquitto:2
    container_name: mqtt-broker
    ports:
      - "1883:1883"
    volumes:
      - ./mqtt/config:/mosquitto/config
      - ./mqtt/data:/mosquitto/data
      - ./mqtt/log:/mosquitto/log
    restart: unless-stopped

Step 8 – Create Mosquitto Configuration

mkdir -p mqtt/config mqtt/data mqtt/log
geany mqtt/config/mosquitto.conf

Paste:

listener 1883
allow_anonymous true

Step 9 – Start MQTT Broker

docker compose up -d
docker ps

Step 10 – Fix File Ownership (If Needed)

docker compose down
sudo chown -R pi:pi ~/projects/iot-gateway
docker compose up -d

Step 11 – Test MQTT

sudo apt install mosquitto-clients -y

Terminal 1:

mosquitto_sub -h localhost -t test/topic

Terminal 2:

mosquitto_pub -h localhost -t test/topic -m "MQTT test successful"

If the message appears, your gateway is working.

What We Have Built

You now have:

• A Raspberry Pi running Docker

• A containerized MQTT broker

• A real IoT gateway foundation

Next, we're ready to attach the sensor modules and perform further processing from Raspberry pi to cloud

Gateway roadmap. In Part 1 we have built the MQTT messaging foundation. In the next parts, we will add data storage, dashboards, and AI-based analysis to turn this into a complete IoT platform.

Coming Up in Part 2

In the next part, we will connect real devices like ESP32 or Raspberry Pi Pico W and start sending live sensor data into this gateway.

This is where the system becomes truly powerful.