Setting up a local standalone cluster
Run Pulsar as a single JVM process for local developmentFor 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:
-
by clicking the link below and downloading the release from an Apache mirror:
- from the Pulsar downloads page
- from the Pulsar releases page
-
using wget:
$ wget http://www.apache.org/dyn/closer.cgi/incubator/pulsar/pulsar-2.0.0-rc1-incubating/apache-pulsar-2.0.0-rc1-incubating-bin.tar.gz
Once the tarball is downloaded, untar it and cd
into the resulting directory:
$ tar xvfz apache-pulsar-2.0.0-rc1-incubating-bin.tar.gz
$ cd apache-pulsar-2.0.0-rc1-incubating
What your package contains
The Pulsar binary package initially contains 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 |
examples |
A Java JAR file containing example Pulsar Functions |
lib |
The JAR files used by Pulsar |
licenses |
License files, in .txt form, for various components of the Pulsar codebase |
These directories will be created once you begin running Pulsar:
Directory | Contains |
---|---|
data |
The data storage directory used by ZooKeeper and BookKeeper |
instances |
Artifacts created for Pulsar Functions |
logs |
Logs created by the installation |
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
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 my-topic
topic:
$ bin/pulsar-client produce my-topic \
--messages "hello-pulsar"
If the message has been successfully published to the topic, you should see a confirmation like this in the pulsar-client
logs:
13:09:39.356 [main] INFO org.apache.pulsar.client.cli.PulsarClientTool - 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";
PulsarClient client = PulsarClient.create(localClusterUrl);
Producer producer = client.createProducer("my-topic");
Here’s an example Python producer:
import pulsar
client = pulsar.Client('pulsar://localhost:6650')
producer = client.create_producer('my-topic')
Finally, here’s an example C++ producer:
Client client("pulsar://localhost:6650");
Producer producer;
Result result = client.createProducer("my-topic", producer);
if (result != ResultOk) {
LOG_ERROR("Error creating producer: " << result);
return -1;
}