Set up a standalone Pulsar in Docker

For local development and testing, you can run Pulsar in standalone mode on your own machine within a Docker container.

If you have not installed Docker, download it following the instructions for your OS.

Start Pulsar in Docker

• For MacOS, Linux, and Windows:

  
  $ docker run -it \
  -p 6650:6650 \
  -p 8080:8080 \
  --mount source=pulsardata,target=/pulsar/data \
  --mount source=pulsarconf,target=/pulsar/conf \
  apachepulsar/pulsar:2.6.4 \
  bin/pulsar standalone
  

A few things to note about this command:

• The data, metadata, and configuration are persisted on Docker volumes in order to not start "fresh" every time the container is restarted. For details on the volumes you can use docker volume inspect <sourcename>
• For Docker on Windows make sure to configure it to use Linux containers

If you start Pulsar successfully, you will see INFO-level log messages like this:

2017-08-09 22:34:04,030 - INFO  - [main:WebService@213] - Web Service started at http://127.0.0.1:8080
2017-08-09 22:34:04,038 - INFO  - [main:PulsarService@335] - messaging service is ready, bootstrap service on port=8080, broker url=pulsar://127.0.0.1:6650, cluster=standalone, configs=org.apache.pulsar.broker.ServiceConfiguration@4db60246
...

tip

When you start a local standalone cluster, a public/default namespace is created automatically. The namespace is used for development purposes. All Pulsar topics are managed within namespaces. For more information, see Topics.

Use Pulsar in Docker

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

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

The following example will guide you get started with Pulsar quickly by using the Python client API.

Install the Pulsar Python client library directly from PyPI:

$ pip install pulsar-client

Consume a message

Create a consumer and subscribe to the topic:

import pulsar

client = pulsar.Client('pulsar://localhost:6650')
consumer = client.subscribe('my-topic',
                            subscription_name='my-sub')

while True:
    msg = consumer.receive()
    print("Received message: '%s'" % msg.data())
    consumer.acknowledge(msg)

client.close()

Produce a message

Now start a producer to send some test messages:

import pulsar

client = pulsar.Client('pulsar://localhost:6650')
producer = client.create_producer('my-topic')

for i in range(10):
    producer.send(('hello-pulsar-%d' % i).encode('utf-8'))

client.close()

Get the topic statistics

In Pulsar, you can use REST, Java, or command-line tools to control every aspect of the system. For details on APIs, refer to Admin API Overview.

In the simplest example, you can use curl to probe the stats for a particular topic:

$ curl http://localhost:8080/admin/v2/persistent/public/default/my-topic/stats | python -m json.tool

The output is something like this:

{
  "averageMsgSize": 0.0,
  "msgRateIn": 0.0,
  "msgRateOut": 0.0,
  "msgThroughputIn": 0.0,
  "msgThroughputOut": 0.0,
  "publishers": [
    {
      "address": "/172.17.0.1:35048",
      "averageMsgSize": 0.0,
      "clientVersion": "1.19.0-incubating",
      "connectedSince": "2017-08-09 20:59:34.621+0000",
      "msgRateIn": 0.0,
      "msgThroughputIn": 0.0,
      "producerId": 0,
      "producerName": "standalone-0-1"
    }
  ],
  "replication": {},
  "storageSize": 16,
  "subscriptions": {
    "my-sub": {
      "blockedSubscriptionOnUnackedMsgs": false,
      "consumers": [
        {
          "address": "/172.17.0.1:35064",
          "availablePermits": 996,
          "blockedConsumerOnUnackedMsgs": false,
          "clientVersion": "1.19.0-incubating",
          "connectedSince": "2017-08-09 21:05:39.222+0000",
          "consumerName": "166111",
          "msgRateOut": 0.0,
          "msgRateRedeliver": 0.0,
          "msgThroughputOut": 0.0,
          "unackedMessages": 0
        }
      ],
      "msgBacklog": 0,
      "msgRateExpired": 0.0,
      "msgRateOut": 0.0,
      "msgRateRedeliver": 0.0,
      "msgThroughputOut": 0.0,
      "type": "Exclusive",
      "unackedMessages": 0
    }
  }
}