Setting up a local standalone cluster

Run Pulsar as a single JVM process for local development

For the purposes of local development and testing, you can run Pulsar in standalone mode on your own machine.

Standalone mode includes a Pulsar broker as well as the necessary ZooKeeper and BookKeeper components running inside of a single Java Virtual Machine (JVM) process.

Pulsar in production?

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

System requirements

Pulsar is currently available for MacOS and Linux. In order to use Pulsar, you’ll need to install Java 8.

Installing Pulsar

To get started running Pulsar, download a binary tarball release in one of the following ways:

Once the tarball is downloaded, untar it and cd into the resulting directory:

# Source release
$ tar xvfz pulsar-1.19.0-incubating-src.tar.gz
$ cd pulsar-1.19.0-incubating

# Binary release
$ tar xvfz apache-pulsar-1.19.0-incubating-bin.tar.gz
$ cd pulsar-1.19.0-incubating

What your package contains

Both the source and binary packages contain the following directories:

Directory Contains
bin Pulsar’s command-line tools, such as pulsar and pulsar-admin
conf Configuration files for Pulsar, including for broker configuration, ZooKeeper configuration, and more
data The data storage directory used by ZooKeeper and BookKeeper.
lib The JAR files used by Pulsar.
logs Logs created by the installation.

The source package contains all of the assets, specific to version 1.19.0-incubating, from the Pulsar repository.

Compiling from source

If you’ve downloaded a source release and would like to compile it, you’ll need to have JDK 8 and Maven installed. To run the scripts in the bin directory, you’ll need to have the Java SE Runtime Environment installed (JDK 8 already includes this).

To compile, skipping the tests:

$ mvn install -DskipTests

Starting the cluster

Once you have an up-to-date local copy of the release, you can start up a local cluster using the pulsar command, which is stored in the bin directory, and specifying that you want to start up Pulsar in standalone mode:

$ bin/pulsar standalone

If Pulsar has been successfully started, you should see INFO-level log messages like this:

2017-06-01 14:46:29,192 - INFO  - [main:WebSocketService@95] - Global Zookeeper cache started
2017-06-01 14:46:29,192 - INFO  - [main:AuthenticationService@61] - Authentication is disabled
2017-06-01 14:46:29,192 - INFO  - [main:WebSocketService@108] - Pulsar WebSocket Service started

Automatically created namespace

When you start a local standalone cluster, Pulsar will automatically create a sample/standalone/ns1 namespace that you can use for development purposes. All Pulsar topics are managed within namespaces. For more info, see Topics.

Testing your cluster setup

Pulsar provides a CLI tool called pulsar-client that enables you to do things like send messages to a Pulsar topic in a running cluster. This command will send a simple message saying hello-pulsar to the persistent://sample/standalone/ns1/my-topic topic:

$ bin/pulsar-client produce \
  persistent://sample/standalone/ns1/my-topic \
  -m 'hello-pulsar'

If the message has been successfully published to the topic, you should see a confirmation like this in the pulsar-client logs:

2017-06-01 18:18:57,094 - INFO  - [main:CmdProduce@189] - 1 messages successfully produced

No need to explicitly create new topics

You may have noticed that we did not explicitly create the my-topic topic to which we sent the hello-pulsar message. If you attempt to write a message to a topic that does not yet exist, Pulsar will automatically create that topic for you.

Using Pulsar clients locally

Pulsar currently offers client libraries for Java, Python, and C++. If you’re running a local standalone cluster, you can use one of these root URLs for interacting with your cluster:

  • http://localhost:8080
  • pulsar://localhost:6650

Here’s an example producer for a Pulsar topic using the Java client:

String localClusterUrl = "pulsar://localhost:6650";
String namespace = "sample/standalone/ns1"; // This namespace is created automatically
String topic = String.format("persistent://%s/my-topic", namespace);

PulsarClient client = PulsarClient.create(localClusterUrl);
Producer producer = client.createProducer(topic);

Here’s an example Python producer:

import pulsar

TOPIC = 'persistent://sample/standalone/ns/my-topic'

client = pulsar.Client('pulsar://localhost:6650')
producer = client.create_producer(TOPIC)

Finally, here’s an example C++ producer:

Client client("pulsar://localhost:6650");
Producer producer;
Result result = client.createProducer("persistent://sample/standalone/ns1/my-topic", producer);
if (result != ResultOk) {
    LOG_ERROR("Error creating producer: " << result);
    return -1;
}