You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by si...@apache.org on 2019/05/15 09:27:47 UTC
[pulsar] branch master updated: Edit *Getting started* for clarity
(#4246)
This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 6c37145 Edit *Getting started* for clarity (#4246)
6c37145 is described below
commit 6c37145d6fdb5a1fdbfaa34db29df002127af187
Author: Anonymitaet <50...@users.noreply.github.com>
AuthorDate: Wed May 15 17:27:42 2019 +0800
Edit *Getting started* for clarity (#4246)
* Edit *Getting started* for clarity
---
site2/docs/getting-started-clients.md | 10 +-
site2/docs/getting-started-docker.md | 58 ++++++-----
site2/docs/getting-started-standalone.md | 161 ++++++++++++++-----------------
3 files changed, 110 insertions(+), 119 deletions(-)
diff --git a/site2/docs/getting-started-clients.md b/site2/docs/getting-started-clients.md
index 258b5ac..a492e3a 100644
--- a/site2/docs/getting-started-clients.md
+++ b/site2/docs/getting-started-clients.md
@@ -1,15 +1,15 @@
---
id: client-libraries
title: Pulsar client libraries
-sidebar_label: Client libraries
+sidebar_label: Use Pulsar with client libraries
---
Pulsar supports the following client libraries:
-* [Java](#java-client)
-* [Go](#go-client)
-* [Python](#python-client)
-* [C++](#c-client)
+- [Java client](#java-client)
+- [Go client](#go-client)
+- [Python client](#python-client)
+- [C++ client](#c-client)
## Java client
diff --git a/site2/docs/getting-started-docker.md b/site2/docs/getting-started-docker.md
index 1fafd7d..70b578f 100644
--- a/site2/docs/getting-started-docker.md
+++ b/site2/docs/getting-started-docker.md
@@ -1,7 +1,7 @@
---
id: standalone-docker
-title: Start a standalone cluster with Docker
-sidebar_label: Pulsar in Docker
+title: Set up a standalone Pulsar in Docker
+sidebar_label: Run Pulsar in Docker
---
For local development and testing, you can run Pulsar in standalone
@@ -10,27 +10,29 @@ mode on your own machine within a Docker container.
If you have not installed Docker, download the [Community edition](https://www.docker.com/community-edition)
and follow the instructions for your OS.
-## Start Pulsar inside Docker
-
-```shell
-$ docker run -it \
- -p 6650:6650 \
- -p 8080:8080 \
- -v $PWD/data:/pulsar/data \
- apachepulsar/pulsar:{{pulsar:version}} \
- bin/pulsar standalone
-```
-
-For Windows, enter something like the following docker command:
-
-```shell
-$ docker run -it \
- -p 6650:6650 \
- -p 8080:8080 \
- -v "$PWD/data:/pulsar/data".ToLower() \
- apachepulsar/pulsar:{{pulsar:version}} \
- bin/pulsar standalone
-```
+## Start Pulsar in Docker
+
+* For MacOS and Linux:
+
+ ```shell
+ $ docker run -it \
+ -p 6650:6650 \
+ -p 8080:8080 \
+ -v $PWD/data:/pulsar/data \
+ apachepulsar/pulsar:{{pulsar:version}} \
+ bin/pulsar standalone
+ ```
+
+* For Windows:
+
+ ```shell
+ $ docker run -it \
+ -p 6650:6650 \
+ -p 8080:8080 \
+ -v "$PWD/data:/pulsar/data".ToLower() \
+ apachepulsar/pulsar:{{pulsar:version}} \
+ bin/pulsar standalone
+ ```
A few things to note about this command:
* `$PWD/data` : The docker host directory in Windows operating system must be lowercase.`$PWD/data` provides you with the specified directory, for example: `E:/data`.
@@ -45,13 +47,13 @@ If you start Pulsar successfully, you will see `INFO`-level log messages like th
...
```
-> #### Automatically created namespace
+> #### 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](concepts-messaging.md#topics).
-
-## Start publishing and consuming messages
+## Use Pulsar in Docker
Pulsar offers client libraries for [Java](client-libraries-java.md), [Go](client-libraries-go.md), [Python](client-libraries-python.md)
and [C++](client-libraries-cpp.md). If you're running a local standalone cluster, you can
@@ -69,6 +71,8 @@ Install the Pulsar Python client library directly from [PyPI](https://pypi.org/p
$ pip install pulsar-client
```
+### Consume a message
+
Create a consumer and subscribe to the topic:
```python
@@ -86,6 +90,8 @@ while True:
client.close()
```
+### Produce a message
+
Now start a producer to send some test messages:
```python
diff --git a/site2/docs/getting-started-standalone.md b/site2/docs/getting-started-standalone.md
index 530b526..e2bca20 100644
--- a/site2/docs/getting-started-standalone.md
+++ b/site2/docs/getting-started-standalone.md
@@ -1,7 +1,7 @@
---
id: standalone
-title: Set up a Local Standalone Pulsar
-sidebar_label: Run Pulsar Locally
+title: Set up a standalone Pulsar locally
+sidebar_label: Run Pulsar locally
---
For local development and testing, you can run Pulsar in standalone mode on your machine. The standalone mode includes a Pulsar broker, the necessary ZooKeeper and BookKeeper components running inside of a single Java Virtual Machine (JVM) process.
@@ -9,24 +9,23 @@ For local development and testing, you can run Pulsar in standalone mode on your
> #### Pulsar in production?
> If you're looking to run a full production Pulsar installation, see the [Deploying a Pulsar instance](deploy-bare-metal.md) guide.
-## Run Pulsar Standalone Manually
+## Install Pulsar standalone
-### System Requirements
+### System requirements
Pulsar is currently available for **MacOS** and **Linux**. To use Pulsar, you need to install [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
-
-### Install Pulsar
+### Install Pulsar using binary release
To get started with 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:
-
- * <a href="pulsar:binary_release_url" download>Pulsar {{pulsar:version}} binary release</a>
+* download from the Apache mirror (<a href="pulsar:binary_release_url" download>Pulsar {{pulsar:version}} binary release</a>)
-* from the Pulsar [downloads page](pulsar:download_page_url)
-* from the Pulsar [releases page](https://github.com/apache/pulsar/releases/latest)
-* using [wget](https://www.gnu.org/software/wget):
+* download from the Pulsar [downloads page](pulsar:download_page_url)
+
+* download from the Pulsar [releases page](https://github.com/apache/pulsar/releases/latest)
+
+* use [wget](https://www.gnu.org/software/wget):
```shell
$ wget pulsar:binary_release_url
@@ -39,7 +38,7 @@ $ tar xvfz apache-pulsar-{{pulsar:version}}-bin.tar.gz
$ cd apache-pulsar-{{pulsar:version}}
```
-### What Your Package Contains
+#### What your package contains
The Pulsar binary package initially contains the following directories:
@@ -59,19 +58,28 @@ Directory | Contains
`instances` | Artifacts created for [Pulsar Functions](functions-overview.md).
`logs` | Logs created by the installation.
+#### Install other optional components
+
+> #### Tip
+> If you want to use builtin connectors and tiered storage offloaders, you can install them according to the following instructions：
+>
+> * [Install builtin connectors (optional)](#install-builtin-connectors-optional)
+> * [Install tiered storage offloaders (optional)](#install-tiered-storage-offloaders-optional)
+>
+> Otherwise, skip this step and perform the next step [Start Pulsar standalone](#start-pulsar-standalone). Pulsar can be successfully installed without installing bulitin connectors and tiered storage offloaders.
-### Install Builtin Connectors (Optional)
+##### Install builtin connectors (optional)
Since `2.1.0-incubating` release, Pulsar releases a separate binary distribution, containing all the `builtin` connectors.
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:
+* download from the Apache mirror <a href="pulsar:connector_release_url" download>Pulsar IO Connectors {{pulsar:version}} release</a>
+
+* download from the Pulsar [downloads page](pulsar:download_page_url)
- * <a href="pulsar:connector_release_url" download>Pulsar IO Connectors {{pulsar:version}} release</a>
+* download from the Pulsar [releases page](https://github.com/apache/pulsar/releases/latest)
-* from the Pulsar [downloads page](pulsar:download_page_url)
-* from the Pulsar [releases page](https://github.com/apache/pulsar/releases/latest)
-* using [wget](https://www.gnu.org/software/wget):
+* use [wget](https://www.gnu.org/software/wget):
```shell
$ wget pulsar:connector_release_url/{connector}-{{pulsar:version}}.nar
@@ -89,29 +97,30 @@ pulsar-io-aerospike-{{pulsar:version}}.nar
...
```
-> #### NOTES
+> #### Note
>
-> If you are running Pulsar in a bare metal cluster, make sure `connectors` tarball is unzipped in every pulsar directory of the broker
+> * If you are running Pulsar in a bare metal cluster, make sure `connectors` tarball is unzipped in every pulsar directory of the broker
> (or in every pulsar directory of function-worker if you are running a separate worker cluster for Pulsar Functions).
>
-> If you are [running Pulsar in Docker](getting-started-docker.md) or deploying Pulsar using a docker image (e.g. [K8S](deploy-kubernetes.md) or [DCOS](deploy-dcos.md)),
+> * If you are [running Pulsar in Docker](getting-started-docker.md) or deploying Pulsar using a docker image (e.g. [K8S](deploy-kubernetes.md) or [DCOS](deploy-dcos.md)),
> you can use the `apachepulsar/pulsar-all` image instead of the `apachepulsar/pulsar` image. `apachepulsar/pulsar-all` image has already bundled [all builtin connectors](io-overview.md#working-with-connectors).
-### Install Tiered Storage Offloaders (Optional)
+##### Install tiered storage offloaders (optional)
+> #### Tip
+>
> Since `2.2.0` release, Pulsar releases a separate binary distribution, containing the tiered storage offloaders.
> To enable tiered storage feature, follow the instructions below; otherwise skip this section.
-To get started with [tiered storage offloaders](concepts-tiered-storage.md), you need to download the offloaders tarball release on every broker node in
-one of the following ways:
+To get started with [tiered storage offloaders](concepts-tiered-storage.md), you need to download the offloaders tarball release on every broker node in one of the following ways:
+
+* download from the Apache mirror <a href="pulsar:offloader_release_url" download>Pulsar Tiered Storage Offloaders {{pulsar:version}} release</a>
-* by clicking the link below and downloading the release from an Apache mirror:
+* download from the Pulsar [downloads page](pulsar:download_page_url)
- * <a href="pulsar:offloader_release_url" download>Pulsar Tiered Storage Offloaders {{pulsar:version}} release</a>
+* download from the Pulsar [releases page](https://github.com/apache/pulsar/releases/latest)
-* from the Pulsar [downloads page](pulsar:download_page_url)
-* from the Pulsar [releases page](https://github.com/apache/pulsar/releases/latest)
-* using [wget](https://www.gnu.org/software/wget):
+* use [wget](https://www.gnu.org/software/wget):
```shell
$ wget pulsar:offloader_release_url
@@ -132,17 +141,16 @@ $ ls offloaders
tiered-storage-jcloud-{{pulsar:version}}.nar
```
-For more details on how to configure tiered storage feature, refer to [Tiered storage cookbook](cookbooks-tiered-storage.md).
+For more information on how to configure tiered storage, see [Tiered storage cookbook](cookbooks-tiered-storage.md).
-> #### NOTES
+> #### Note
>
-> If you are running Pulsar in a bare metal cluster, make sure that `offloaders` tarball is unzipped in every broker's pulsar directory.
+> * If you are running Pulsar in a bare metal cluster, make sure that `offloaders` tarball is unzipped in every broker's pulsar directory.
>
-> If you are [running Pulsar in Docker](getting-started-docker.md) or deploying Pulsar using a docker image (e.g. [K8S](deploy-kubernetes.md) or [DCOS](deploy-dcos.md)),
+> * If you are [running Pulsar in Docker](getting-started-docker.md) or deploying Pulsar using a docker image (e.g. [K8S](deploy-kubernetes.md) or [DCOS](deploy-dcos.md)),
> you can use the `apachepulsar/pulsar-all` image instead of the `apachepulsar/pulsar` image. `apachepulsar/pulsar-all` image has already bundled tiered storage offloaders.
-
-### Start Pulsar Standalone
+## Start Pulsar standalone
Once you have an up-to-date local copy of the release, you can start a local cluster using the [`pulsar`](reference-cli-tools.md#pulsar) command, which is stored in the `bin` directory, and specifying that you want to start Pulsar in standalone mode.
@@ -158,78 +166,55 @@ If you have started Pulsar successfully, you will see `INFO`-level log messages
2017-06-01 14:46:29,192 - INFO - [main:WebSocketService@108] - Pulsar WebSocket Service started
```
-> #### TIP
-> * The service is running on your terminal, which is under your direct control. If you need to run other commands, open a new terminal window. You can also run the service as a background process using the command `pulsar-daemon start standalone`. For more information, see [pulsar-daemon](https://pulsar.apache.org/docs/en/reference-cli-tools/#pulsar-daemon).
-
+> #### Tip
+>
+> * The service is running on your terminal, which is under your direct control. If you need to run other commands, open a new terminal window.
+You can also run the service as a background process using the `pulsar-daemon start standalone` command. For more information, see [pulsar-daemon](https://pulsar.apache.org/docs/en/reference-cli-tools/#pulsar-daemon).
+>
> * When you start a local standalone cluster, a `public/default` [namespace](concepts-messaging.md#namespaces) is created automatically. The namespace is used for development purposes. All Pulsar topics are managed within namespaces. For more information, see [Topics](concepts-messaging.md#topics).
-## Run Pulsar Standalone in Docker
+## Use Pulsar standalone
-Alternatively, you can run a Pulsar standalone locally in docker.
+Pulsar provides a CLI tool called [`pulsar-client`](reference-cli-tools.md#pulsar-client). The pulsar-client tool enables you to consume and produce messages to a Pulsar topic in a running cluster.
+
+### Consume a message
+
+The following command consumes a message with the subscription name `first-subscription` to the `my-topic` topic:
```bash
-docker run -it -p 80:80 -p 8080:8080 -p 6650:6650 apachepulsar/pulsar-standalone
+$ bin/pulsar-client consume my-topic -s "first-subscription"
```
-The command forwards the following port to localhost:
+If the message has been successfully consumed, you will see a confirmation like the following in the `pulsar-client` logs:
-- 80: the port for Pulsar dashboard
-- 8080: the HTTP service URL for Pulsar service
-- 6650: the binary protocol service URL for Pulsar service
+```
+09:56:55.566 [pulsar-client-io-1-1] INFO org.apache.pulsar.client.impl.MultiTopicsConsumerImpl - [TopicsConsumerFakeTopicNamee2df9] [first-subscription] Success subscribe new topic my-topic in topics consumer, partitions: 4, allTopicPartitionsNumber: 4
+```
-After the docker container is running, you can access the dashboard at http://localhost.
+> #### Tip
+>
+> As you have noticed that we do not explicitly create the `my-topic` topic, to which we consume the message. When you consume a message to a topic that does not yet exist, Pulsar creates that topic for you automatically. Producing a message to a topic that does not exist will automatically create that topic for you as well.
-## Test Your Cluster Setup
+### Produce a message
-Pulsar provides a CLI tool called [`pulsar-client`](reference-cli-tools.md#pulsar-client). The pulsar-client enables you to send messages to a Pulsar topic in a running cluster. The following command sends a message saying `hello-pulsar` to the `my-topic` topic:
+The following command produces a message saying `hello-pulsar` to the `my-topic` topic:
```bash
$ bin/pulsar-client produce my-topic --messages "hello-pulsar"
```
-If the message has been successfully published to the topic, you will see a confirmation like this in the `pulsar-client` logs:
+If the message has been successfully published to the topic, you will see a confirmation like the following in the `pulsar-client` logs:
```
13:09:39.356 [main] INFO org.apache.pulsar.client.cli.PulsarClientTool - 1 messages successfully produced
```
+## Stop Pulsar standalone
-> #### No need to create new topics explicitly
-> As you have noticed that we do not explicitly create the `my-topic` topic, to which we sent the `hello-pulsar` message. When you write a message to a topic that does not yet exist, Pulsar creates that topic for you automatically.
+Press `Ctrl+C` to stop a local standalone Pulsar.
-## Use Pulsar Clients Locally
-
-Pulsar currently offers client libraries for [Java](client-libraries-java.md), [Go](client-libraries-go.md), [Python](client-libraries-python.md) and [C++](client-libraries-cpp.md). If you run a local standalone cluster, you can use one of these root URLs to interact with your cluster:
-
-* `http://localhost:8080`
-* `pulsar://localhost:6650`
-
-The following is an example of producer for a Pulsar topic using the [Java](client-libraries-java.md) client:
-
-```java
-String localClusterUrl = "pulsar://localhost:6650";
-
-PulsarClient client = PulsarClient.builder().serviceUrl(localClusterUrl).build();
-Producer<byte[]> producer = client.newProducer().topic("my-topic").create();
-```
-
-The following is an example of [Python](client-libraries-python.md) producer:
-
-```python
-import pulsar
-
-client = pulsar.Client('pulsar://localhost:6650')
-producer = client.create_producer('my-topic')
-```
-
-The following is an example of [C++](client-libraries-cpp.md) producer:
-
-```cpp
-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;
-}
-```
+> #### Tip
+>
+> If the service runs as a background process using the `pulsar-daemon start standalone` command, then use the `pulsar-daemon stop standalone` command to stop the service.
+>
+> For more information, see [pulsar-daemon](https://pulsar.apache.org/docs/en/reference-cli-tools/#pulsar-daemon).