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.
Currently, Pulsar is available for 64-bit macOS, Linux, and Windows. To use Pulsar, you need to install 64-bit JRE/JDK 8 or later versions.
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 pulsar:binary_release_url
Once the tarball is downloaded, untar it and cd
into the resulting directory:
$ tar xvfz apache-pulsar-{{pulsar:version}}-bin.tar.gz $ cd apache-pulsar-{{pulsar:version}}
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 |
Since release 2.1.0-incubating
, Pulsar releases a separate binary distribution, containing all the builtin
connectors. If you would like to enable those builtin
connectors, you can download the connectors 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 pulsar:connector_release_url
Once the tarball is downloaded, in the pulsar directory, untar the io-connectors package and copy the connectors as connectors
in the pulsar directory:
$ tar xvfz /path/to/apache-pulsar-io-connectors-{{pulsar:version}}-bin.tar.gz // you will find a directory named `apache-pulsar-io-connectors-{{pulsar:version}}` in the pulsar directory // then copy the connectors $ cd apache-pulsar-io-connectors-{{pulsar:version}}/connectors connectors $ ls connectors pulsar-io-aerospike-{{pulsar:version}}.nar pulsar-io-cassandra-{{pulsar:version}}.nar pulsar-io-kafka-{{pulsar:version}}.nar pulsar-io-kinesis-{{pulsar:version}}.nar pulsar-io-rabbitmq-{{pulsar:version}}.nar pulsar-io-twitter-{{pulsar:version}}.nar ...
NOTES
If you are running Pulsar in a bare metal cluster, you need to make sure
connectors
tarball is unzipped in every broker‘s pulsar directory (or in every function-worker’s pulsar directory if you are running a separate worker cluster for Pulsar functions).If you are running Pulsar in Docker or deploying Pulsar using a docker image (e.g. K8S or DCOS), you can use
apachepulsar/pulsar-all
image instead ofapachepulsar/pulsar
image.apachepulsar/pulsar-all
image has already bundled all builtin connectors.
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] - Configuration Store 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
public/default
namespace that you can use for development purposes. All Pulsar topics are managed within namespaces. For more info, see Topics.
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 thehello-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.
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.builder().serviceUrl(localClusterUrl).build(); Producer<byte[]> producer = client.newProducer().topic("my-topic").create();
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; }