Installation

Apache Pulsar can be deployed in various ways depending on your use case. This guide covers installation methods from simple standalone deployments to production-ready Kubernetes clusters.

Java requirements

Pulsar requires Java to run. Make sure you have the correct Java version installed before proceeding.

Pulsar’s Java version requirements vary by version and component:

Pulsar 4.1+ and master branch

Component	Java Version
Broker	21
Functions / IO	21
CLI	17 or 21
Java Client	17 or 21

Docker image Java runtime: 21

Pulsar 3.3 to 4.0

Component	Java Version
Broker	21
Functions / IO	21
CLI	17 or 21
Java Client	8, 11, 17 or 21

Docker image Java runtime: 21

Pulsar 2.10 to 3.0

Component	Java Version
Broker	17
Functions / IO	17
CLI	17
Java Client	8, 11, or 17

Docker image Java runtime: 17

When using Java versions, it is recommended to use a recent version of a particular Java release (17 or 21) with the most recent bug fixes and security patches. Download from Eclipse Temurin.

Docker installation

The easiest way to run Pulsar is using Docker. This method is ideal for development, testing, and getting started quickly.

Standalone mode

Pull the Pulsar image

Download the latest Pulsar Docker image:

docker pull apachepulsar/pulsar:latest

The pulsar:latest image includes the Pulsar broker, BookKeeper, and ZooKeeper. For a complete image with all connectors and tools, use apachepulsar/pulsar-all:latest.

Start Pulsar standalone

Run Pulsar in standalone mode with a single command:

docker run -it \
  -p 6650:6650 \
  -p 8080:8080 \
  --name pulsar-standalone \
  apachepulsar/pulsar:latest \
  bin/pulsar standalone

This exposes:

Port 6650: Pulsar broker (binary protocol)
Port 8080: HTTP API and admin interface

Verify the installation

Check that Pulsar is running:

# Check broker status
docker exec -it pulsar-standalone bin/pulsar-admin brokers healthcheck

# List topics
docker exec -it pulsar-standalone bin/pulsar-admin topics list public/default

Persist data with volumes

By default, data is stored inside the container and will be lost when the container stops. To persist data:

docker run -it \
  -p 6650:6650 \
  -p 8080:8080 \
  -v $PWD/data:/pulsar/data \
  --name pulsar-standalone \
  apachepulsar/pulsar:latest \
  bin/pulsar standalone

Docker Compose for multi-node setup

For a more production-like environment with multiple brokers and bookies, use Docker Compose. Here’s an example based on the Pulsar source code:

# Based on source: tests/compose/simple/docker-compose.yml
version: '2.1'

networks:
  pulsar:
    driver: bridge

services:
  zk:
    hostname: zk
    image: apachepulsar/pulsar:latest
    command: bin/pulsar zookeeper
    environment:
      ZOOKEEPER_SERVERS: zk
    networks:
      - pulsar

  pulsar-init:
    image: apachepulsar/pulsar:latest
    command: >
      bin/pulsar initialize-cluster-metadata
        --cluster test
        --zookeeper zk:2181
        --configuration-store zk:2181
        --web-service-url http://broker:8080
        --broker-service-url pulsar://broker:6650
    depends_on:
      - zk
    networks:
      - pulsar

  bookie:
    hostname: bookie
    image: apachepulsar/pulsar:latest
    command: bin/pulsar bookie
    environment:
      clusterName: test
      zkServers: zk:2181
    depends_on:
      - zk
      - pulsar-init
    networks:
      - pulsar

  broker:
    hostname: broker
    image: apachepulsar/pulsar:latest
    command: bin/pulsar broker
    environment:
      clusterName: test
      zookeeperServers: zk:2181
      configurationStoreServers: zk:2181
    ports:
      - "6650:6650"
      - "8080:8080"
    depends_on:
      - zk
      - bookie
      - pulsar-init
    networks:
      - pulsar

To start the cluster:

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f broker

# Stop all services
docker-compose down

Standalone binary installation

For local development or single-machine deployments, you can install Pulsar as a standalone binary.

Download Pulsar

Download the latest release from the Apache Pulsar website:

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

Or download from the official downloads page.

Extract the archive

Extract the downloaded tarball:

tar xvfz apache-pulsar-3.3.0-bin.tar.gz
cd apache-pulsar-3.3.0

Start Pulsar standalone

Run Pulsar in standalone mode:

bin/pulsar standalone

Standalone mode is available via the bin/pulsar CLI tool with the standalone command, as defined in bin/pulsar:60.

Run in the background

To run Pulsar as a background service:

# Start in background
bin/pulsar-daemon start standalone

# Check status
bin/pulsar-admin brokers healthcheck

# Stop the service
bin/pulsar-daemon stop standalone

Configure standalone mode

Standalone configuration is located at conf/standalone.conf. Key settings include:

# Broker service port
brokerServicePort=6650

# Web service port
webServicePort=8080

# Data directories
zookeeperServers=localhost:2181

Kubernetes installation

For production deployments, Kubernetes is the recommended platform. Pulsar provides official Helm charts for easy deployment.

Kubernetes installation requires familiarity with Kubernetes concepts and kubectl command-line tool.

Prerequisites

Kubernetes cluster (1.20+)
kubectl configured to access your cluster
Helm 3.x installed

Install with Helm

Add the Pulsar Helm repository

helm repo add apache https://pulsar.apache.org/charts
helm repo update

Create a namespace

kubectl create namespace pulsar

Install Pulsar

Install with default values:

helm install pulsar apache/pulsar \
  --namespace pulsar \
  --set initialize=true

Or customize the installation:

helm install pulsar apache/pulsar \
  --namespace pulsar \
  --set initialize=true \
  --set broker.replicaCount=3 \
  --set bookkeeper.replicaCount=3 \
  --set zookeeper.replicaCount=3

Verify the installation

Check that all pods are running:

kubectl get pods -n pulsar

You should see pods for:

ZooKeeper (3 replicas)
BookKeeper (3 replicas)
Pulsar brokers (3 replicas)
Pulsar proxy

Access the cluster

Forward the proxy port to your local machine:

kubectl port-forward -n pulsar svc/pulsar-proxy 6650:6650 8080:8080

Now you can connect to pulsar://localhost:6650.

Production considerations

For production deployments, consider:

Persistent storage: Configure persistent volumes for BookKeeper and ZooKeeper
Resource limits: Set appropriate CPU and memory limits
Monitoring: Enable Prometheus metrics and Grafana dashboards
Security: Configure TLS, authentication, and authorization
High availability: Use multiple replicas for all components
Anti-affinity: Distribute pods across nodes and availability zones

Example Helm values for production:

# values.yaml
zookeeper:
  replicaCount: 3
  resources:
    requests:
      memory: 2Gi
      cpu: 1
  persistence:
    enabled: true
    size: 20Gi

bookkeeper:
  replicaCount: 3
  resources:
    requests:
      memory: 4Gi
      cpu: 2
  persistence:
    enabled: true
    journal:
      size: 10Gi
    ledgers:
      size: 50Gi

broker:
  replicaCount: 3
  resources:
    requests:
      memory: 4Gi
      cpu: 2

proxy:
  replicaCount: 2
  resources:
    requests:
      memory: 512Mi
      cpu: 0.5

monitoring:
  prometheus: true
  grafana: true

Install with custom values:

helm install pulsar apache/pulsar \
  --namespace pulsar \
  --values values.yaml

Build from source

If you need to build Pulsar from source, follow these steps:

Requirements

JDK 21 (for master/4.0+) or JDK 17 (for 2.11+)
Maven 3.9.9+
zip

Pulsar includes a Maven Wrapper, so you can use ./mvnw instead of mvn if you don’t have Maven installed.

Build steps

Clone the repository

git clone https://github.com/apache/pulsar.git
cd pulsar

Build Pulsar

Compile and install:

mvn install -DskipTests

For a minimal build (skips external connectors):

mvn install -Pcore-modules,-main -DskipTests

Find the distribution

The built distribution is located at:

distribution/server/target/apache-pulsar-<version>-bin.tar.gz

Extract and run

cd distribution/server/target
tar xvfz apache-pulsar-*-bin.tar.gz
cd apache-pulsar-*
bin/pulsar standalone

Build Docker images

To build custom Docker images:

mvn clean install -DskipTests
export DOCKER_CLI_EXPERIMENTAL=enabled
mvn package -Pdocker,-main -am -pl docker/pulsar-all -DskipTests

This creates:

apachepulsar/pulsar-all:latest
apachepulsar/pulsar:latest

Verify your installation

Regardless of installation method, verify Pulsar is working:

pulsar-admin brokers healthcheck

Next steps

Quickstart guide

Try Pulsar with a simple pub-sub example

Configuration

Learn about configuration options

Client libraries

Connect to Pulsar from your applications

Admin API

Manage your Pulsar cluster

All code examples and configurations are extracted from the Apache Pulsar source code to ensure accuracy and authenticity.

Getting Started

Core Concepts

Client Libraries

Pulsar Functions

Pulsar IO

Deployment

Operations

Security

Java requirements

Pulsar 4.1+ and master branch

Pulsar 3.3 to 4.0

Pulsar 2.10 to 3.0

Docker installation

Standalone mode

Persist data with volumes

Docker Compose for multi-node setup

Standalone binary installation

Configure standalone mode

Kubernetes installation

Prerequisites

Install with Helm

Production considerations

Build from source

Requirements

Build steps

Build Docker images

Verify your installation

Next steps

Quickstart guide

Configuration

Client libraries

Admin API

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Client Libraries

Pulsar Functions

Pulsar IO

Deployment

Operations

Security

​Java requirements

​Pulsar 4.1+ and master branch

​Pulsar 3.3 to 4.0

​Pulsar 2.10 to 3.0

​Docker installation

​Standalone mode

​Persist data with volumes

​Docker Compose for multi-node setup

​Standalone binary installation

​Configure standalone mode

​Kubernetes installation

​Prerequisites

​Install with Helm

​Production considerations

​Build from source

​Requirements

​Build steps

​Build Docker images

​Verify your installation

​Next steps

Quickstart guide

Configuration

Client libraries

Admin API

Build docs developers (and LLMs) love

Java requirements

Pulsar 4.1+ and master branch

Pulsar 3.3 to 4.0

Pulsar 2.10 to 3.0

Docker installation

Standalone mode

Persist data with volumes

Docker Compose for multi-node setup

Standalone binary installation

Configure standalone mode

Kubernetes installation

Prerequisites

Install with Helm

Production considerations

Build from source

Requirements

Build steps

Build Docker images

Verify your installation

Next steps