Quick Start

Welcome to FlowMQ! This guide will walk you through installing the FlowMQ CLI, launching a free development instance, and running basic messaging patterns. You'll learn how to use pure MQTT, pure Kafka, and then combine them to see the unifying power of FlowMQ.

Prerequisites

• Basic understanding of MQTT and Kafka.
• Terminal/Command line access.
• Python 3: With pip installed. We'll use this for our application examples.

Provisioning Your First FlowMQ Instance

We'll use the flow Command Line Interface (CLI) to spin up a free, sandboxed FlowMQ instance directly from your terminal.

Install the Flow CLI

Install our official CLI using your preferred package manager.

• Homebrew (macOS/Linux):

brew install flowmq/tap/flow

• Chocolatey (Windows):

choco install flow

If you don't have a package manager, download and install the latest flow CLI release from our website.

curl -L https://get.flowmq.io | bash

Authenticate the CLI

Link the CLI to your FlowMQ account to manage your resources.

flow auth login

This command will open a browser window for you to log in and grant the CLI access to your FlowMQ account.

1.2.3 Launch a Free Instance

Now, launch a new, free-tier "Dev Instance" of FlowMQ.

flow instances create --name my-first-flow

The CLI will provision the instance and, once ready, output its Bootstrap Server URL and create a set of default Credentials (Access Key & Secret). You will need these for the following steps.

MQTT Publish & Subscribe

Let's start with a standard "Hello World" using only the MQTT protocol. This confirms your instance is running and you can connect to it.

Install MQTT Client Library

We'll use the popular paho-mqtt library for Python.

pip install paho-mqtt

Create the publisher_mqtt.py file

Use the credentials from the flow instances create command.

# publisher_mqtt.py
import paho.mqtt.client as mqtt

# --- Use your instance details ---
BROKER = "your-bootstrap-url.flowmq.cloud"
PORT = 1883
ACCESS_KEY = "your-access-key"
SECRET_KEY = "your-secret-key"

client = mqtt.Client(client_id="mqtt-publisher-1")
client.username_pw_set(ACCESS_KEY, SECRET_KEY)
client.connect(BROKER, PORT)
client.publish("sensors/temperature", "22.5°C")
print("Message '22.5°C' sent to topic 'sensors/temperature'")
client.disconnect()

Create the subscriber_mqtt.py file

# subscriber_mqtt.py
import paho.mqtt.client as mqtt

# --- Use your instance details ---
BROKER = "your-bootstrap-url.flowmq.cloud"
PORT = 1883
ACCESS_KEY = "your-access-key"
SECRET_KEY = "your-secret-key"

def on_message(client, userdata, msg):
    print(f"Received: '{msg.payload.decode()}' on topic '{msg.topic}'")

client = mqtt.Client(client_id="mqtt-subscriber-1")
client.username_pw_set(ACCESS_KEY, SECRET_KEY)
client.on_message = on_message
client.connect(BROKER, PORT)
client.subscribe("sensors/temperature")
print("Waiting for messages on topic 'sensors/temperature'...")
client.loop_forever()

Run the Example

Open two terminals. In the first, start the subscriber. In the second, run the publisher.

Terminal 1: python subscriber_mqtt.py Terminal 2: python publisher_mqtt.py You will see the "Received..." message appear in Terminal 1.

Kafka Produce & Consume

Next, let's do the same thing, but this time using only the Kafka protocol to interact with the same FlowMQ instance.

Install Kafka Client Library

pip install kafka-python

Create the producer_kafka.py file

TODO: (Provide code snippets for producer_kafka.py and consumer_kafka.py, similar in structure to the MQTT examples, using the same Bootstrap URL but with the Kafka port (e.g., 9092) and SASL authentication.)

Create the consumer_kafka.py file

TODO: (Provide code snippets for producer_kafka.py and consumer_kafka.py, similar in structure to the MQTT examples, using the same Bootstrap URL but with the Kafka port (e.g., 9092) and SASL authentication.)

Run the Example

Just like before, run the consumer in one terminal and the producer in another to see the message flow.

The Magic - MQTT to Kafka

This is where FlowMQ's unified architecture shines. We will publish a message using our simple MQTT client and receive it with our Kafka consumer. No code changes are needed in your applications.

Run the Kafka Consumer

Start the Kafka consumer, still have it consume from the topic sensors.temperature.

• Terminal 1: python consumer_kafka.py --topic sensors.temperature

Run the MQTT Publisher

Now, run the MQTT publisher, have it publish to the topic sensor\temperature

• Terminal 2: python publisher_mqtt.py

Witness the Magic

Look at Terminal 1. Your Kafka consumer will receive the message "22.5°C", even though it was published by an MQTT client. You have successfully bridged two protocols without any extra brokers or connectors.

Cleaning Up

To avoid incurring any charges after your trial period, you can easily tear down the resources you created.

Delete the Dev Instance

Use the CLI to de-provision your FlowMQ instance. This will delete all topics and data associated with it.

flow instances delete my-first-flow

Next Steps

Congrats! You've mastered the basics of FlowMQ.

• Learn about Core Concepts and Architecture
• Explore more supported Protocols
• Read the Full CLI Reference: Discover what else you can do with the flow command.