Run a standalone Pulsar cluster locally

For local development and testing, you can run Pulsar in standalone mode on your machine. The standalone mode runs all components inside a single Java Virtual Machine (JVM) process.

tip

If you’re looking to run a full production Pulsar installation, see the Deploying a Pulsar instance guide.

To run Pulsar in standalone mode on your machine, follow the steps below.

Step 0: Prerequisites

Currently, Pulsar is available for 64-bit macOS and Linux. See Run Pulsar In Docker if you want to run Pulsar on Windows.

Also, you need the proper 64-bit JRE/JDK version installed. Please refer to Pulsar Runtime Java Version Recommendation.

Step 1: Download Pulsar distribution

Download the official Apache Pulsar distribution:

wget https://archive.apache.org/dist/pulsar/pulsar-4.0.0/apache-pulsar-4.0.0-bin.tar.gz

Once downloaded, unpack the tar file:

tar xvfz apache-pulsar-4.0.0-bin.tar.gz

For the rest of this quickstart all commands are run from the root of the distribution folder, so switch to it:

cd apache-pulsar-4.0.0

List the contents by executing:

ls -1F

The following directories are created:

Step 2: Start a Pulsar standalone cluster

Run this command to start a standalone Pulsar cluster:

bin/pulsar standalone

When the Pulsar cluster starts, the following directories are created:

tip

• To run the service as a background process, you can use the bin/pulsar-daemon start standalone command. For more information, see pulsar-daemon.
• The public/default namespace is created when you start a Pulsar cluster. This namespace is for development purposes. All Pulsar topics are managed within namespaces. For more information, see Namespaces and Topics.

Step 3: Create a topic

Pulsar stores messages in topics. It’s a good practice to explicitly create topics before using them, even if Pulsar can automatically create topics when they are referenced.

To create a new topic, run this command:

bin/pulsar-admin topics create persistent://public/default/my-topic

Step 4: Write messages to the topic

You can use the pulsar command line tool to write messages to a topic. This is useful for experimentation, but in practice you’ll use the Producer API in your application code, or Pulsar IO connectors for pulling data in from other systems to Pulsar.

Run this command to produce a message:

bin/pulsar-client produce my-topic --messages 'Hello Pulsar!'

Step 5: Read messages from the topic

Now that some messages have been written to the topic, run this command to launch the consumer and read those messages back:

bin/pulsar-client consume my-topic -s 'my-subscription' -p Earliest -n 0

Earliest means consuming from the earliest unconsumed message. -n configures the number of messages to consume, 0 means to consume forever.

As before, this is useful for experimenting with messages, but in practice you’ll use the Consumer API in your application code, or Pulsar IO connectors for reading data from Pulsar to push to other systems.

You’ll see the messages you produce in the previous step:

----- got message -----
key:[null], properties:[], content:Hello Pulsar!

Step 6: Write some more messages

Leave the consume command from the previous step running. If you’ve already closed it, just re-run it.

Now open a new terminal window and produce more messages. The default message separator is ,:

bin/pulsar-client produce my-topic --messages "$(seq -s, -f 'Message NO.%g' 1 10)"

Note how they are displayed almost instantaneously in the consumer terminal.

Step 7: Stop the Pulsar cluster

Once you’ve finished you can shut down the Pulsar cluster. Press Ctrl-C in the terminal window in which you started the cluster.

Related Topics

• Pulsar Concepts and Architecture
• Pulsar Client Libraries
• Pulsar Connectors
• Pulsar Functions