Skip to content

Commit

Permalink
update site2/docs/concepts-overview.md file (apache#4114)
Browse files Browse the repository at this point in the history 
### Motivation
Refine some typos when reading the document.

### Modifications
1. Refine some sentences to be a little more smooth.
2. Avoid using ’s to show the possessive form of inanimate objects. 
3. Add periods for all lists. It is to keep styles consistent.
  • Loading branch information
@Jennifer88huang-zz @sijie
Jennifer88huang-zz authored and sijie committed Apr 26, 2019
1 parent c1b8442 commit f1f6b0c
Showing 1 changed file with 45 additions and 46 deletions.
91 changes: 45 additions & 46 deletions site2/docs/getting-started-standalone.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Setting up a local standalone cluster
sidebar_label: Run Pulsar locally
---

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.
For local development and testing, you can run Pulsar in standalone mode on your own machine. Standalone mode includes a Pulsar broker, 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](deploy-bare-metal.md) guide.
Expand All @@ -13,12 +13,12 @@ For the purposes of local development and testing, you can run Pulsar in standal

### System requirements

Pulsar is currently available for **MacOS** and **Linux**. In order to use Pulsar, you'll need to install [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
Pulsar is currently available for **MacOS** and **Linux**. In order to use Pulsar, you need to install [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).


### Installing Pulsar

To get started running Pulsar, download a binary tarball release in one of the following ways:
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:

Expand All @@ -32,7 +32,7 @@ To get started running Pulsar, download a binary tarball release in one of the f
$ wget pulsar:binary_release_url
```

Once the tarball is downloaded, untar it and `cd` into the resulting directory:
After you download the tarball, untar it and use the `cd` command to navigate to the resulting directory:

```bash
$ tar xvfz apache-pulsar-{{pulsar:version}}-bin.tar.gz
Expand All @@ -45,25 +45,25 @@ The Pulsar binary package initially contains the following directories:

Directory | Contains
:---------|:--------
`bin` | Pulsar's command-line tools, such as [`pulsar`](reference-cli-tools.md#pulsar) and [`pulsar-admin`](reference-pulsar-admin.md)
`conf` | Configuration files for Pulsar, including for [broker configuration](reference-configuration.md#broker), [ZooKeeper configuration](reference-configuration.md#zookeeper), and more
`examples` | A Java JAR file containing example [Pulsar Functions](functions-overview.md)
`lib` | The [JAR](https://en.wikipedia.org/wiki/JAR_(file_format)) files used by Pulsar
`licenses` | License files, in `.txt` form, for various components of the Pulsar [codebase](https://github.com/apache/pulsar)
`bin` | Pulsar's command-line tools, such as [`pulsar`](reference-cli-tools.md#pulsar) and [`pulsar-admin`](reference-pulsar-admin.md).
`conf` | Configuration files for Pulsar, including [broker configuration](reference-configuration.md#broker), [ZooKeeper configuration](reference-configuration.md#zookeeper), and more.
`examples` | A Java JAR file containing [Pulsar Functions](functions-overview.md) example.
`lib` | The [JAR](https://en.wikipedia.org/wiki/JAR_(file_format)) files used by Pulsar.
`licenses` | License files, in the`.txt` form, for various components of the Pulsar [codebase](https://github.com/apache/pulsar).

These directories will be created once you begin running Pulsar:
These directories are created once you begin running Pulsar.

Directory | Contains
:---------|:--------
`data` | The data storage directory used by ZooKeeper and BookKeeper
`instances` | Artifacts created for [Pulsar Functions](functions-overview.md)
`logs` | Logs created by the installation
`data` | The data storage directory used by ZooKeeper and BookKeeper.
`instances` | Artifacts created for [Pulsar Functions](functions-overview.md).
`logs` | Logs created by the installation.


### Installing Builtin Connectors (optional)

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:
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:

Expand All @@ -77,8 +77,8 @@ If you would like to enable those `builtin` connectors, you can download the con
$ wget pulsar:connector_release_url/{connector}-{{pulsar:version}}.nar
```

Once the nar file is downloaded, copy the file to directory `connectors` in the pulsar directory,
for example, if the connector file `pulsar-io-aerospike-{{pulsar:version}}.nar` is downloaded:
After you download the nar file, copy the file to the `connectors` directory in the pulsar directory.
For example, if you download the `pulsar-io-aerospike-{{pulsar:version}}.nar` connector file, enter the following commands:

```bash
$ mkdir connectors
Expand All @@ -91,19 +91,18 @@ pulsar-io-aerospike-{{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 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)),
> you can use `apachepulsar/pulsar-all` image instead of `apachepulsar/pulsar` image. `apachepulsar/pulsar-all` image has already bundled [all builtin connectors](io-overview.md#working-with-connectors).
> 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).
## Installing Tiered Storage Offloaders (optional)

> Since release `2.2.0`, Pulsar releases a separate binary distribution, containing the tiered storage offloaders.
> If you would like to enable tiered storage feature, you can follow the instructions as below; otherwise you can
> skip this section for now.
> 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 using [tiered storage offloaders](concepts-tiered-storage.md), you'll need to download the offloaders tarball release on every broker node in
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:

* by clicking the link below and downloading the release from an Apache mirror:
Expand All @@ -118,7 +117,7 @@ one of the following ways:
$ wget pulsar:offloader_release_url
```

Once the tarball is downloaded, in the pulsar directory, untar the offloaders package and copy the offloaders as `offloaders`
After you download the tarball, untar the offloaders package and copy the offloaders as `offloaders`
in the pulsar directory:

```bash
Expand All @@ -133,25 +132,25 @@ $ ls offloaders
tiered-storage-jcloud-{{pulsar:version}}.nar
```

For more details of how to configure tiered storage feature, you could reference this [Tiered storage cookbook](cookbooks-tiered-storage.md)
For more details on how to configure tiered storage feature, refer to [Tiered storage cookbook](cookbooks-tiered-storage.md).

> #### NOTES
>
> If you are running Pulsar in a bare metal cluster, you need to make sure `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)),
> you can use `apachepulsar/pulsar-all` image instead of `apachepulsar/pulsar` image. `apachepulsar/pulsar-all` image has already bundled tiered storage offloaders.
> you can use the `apachepulsar/pulsar-all` image instead of the `apachepulsar/pulsar` image. `apachepulsar/pulsar-all` image has already bundled tiered storage offloaders.

### 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`](reference-cli-tools.md#pulsar) command, which is stored in the `bin` directory, and specifying that you want to start up Pulsar in standalone mode:
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.

```bash
$ bin/pulsar standalone
```

If Pulsar has been successfully started, you should see `INFO`-level log messages like this:
If you have started Pulsar successfully, you will see `INFO`-level log messages like this:

```bash
2017-06-01 14:46:29,192 - INFO - [main:WebSocketService@95] - Configuration Store cache started
Expand All @@ -160,50 +159,50 @@ If Pulsar has been successfully started, you should see `INFO`-level log message
```

> #### Automatically created namespace
> When you start a local standalone cluster, Pulsar will automatically create a `public/default` [namespace](concepts-messaging.md#namespaces) that you can use for development purposes. All Pulsar topics are managed within namespaces. For more info, see [Topics](concepts-messaging.md#topics).
> 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

Alternatively, you can run pulsar standalone locally in docker.
Alternatively, you can run a Pulsar standalone locally in docker.

```bash
docker run -it -p 80:80 -p 8080:8080 -p 6650:6650 apachepulsar/pulsar-standalone
```

The command forwards following port to localhost:
The command forwards the following port to localhost:

- 80: the port for pulsar dashboard
- 8080: the http service url for pulsar service
- 6650: the binary protocol service url for pulsar service
- 80: the port for Pulsar dashboard
- 8080: the HTTP service URL for Pulsar service
- 6650: the binary protocol service URL for Pulsar service

After the docker container is running, you can access the dashboard under http://localhost .
After the docker container is running, you can access the dashboard at http://localhost.

## Testing your cluster setup

Pulsar provides a CLI tool called [`pulsar-client`](reference-cli-tools.md#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:
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:

```bash
$ 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:
If the message has been successfully published to the topic, you will 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.
> #### 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.
## Using 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're running a local standalone cluster, you can use one of these root URLs for interacting with your cluster:
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`

Here's an example producer for a Pulsar topic using the [Java](client-libraries-java.md) client:
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";
Expand All @@ -212,7 +211,7 @@ PulsarClient client = PulsarClient.builder().serviceUrl(localClusterUrl).build()
Producer<byte[]> producer = client.newProducer().topic("my-topic").create();
```

Here's an example [Python](client-libraries-python.md) producer:
The following is an example of [Python](client-libraries-python.md) producer:

```python
import pulsar
Expand All @@ -221,7 +220,7 @@ client = pulsar.Client('pulsar://localhost:6650')
producer = client.create_producer('my-topic')
```

Finally, here's an example [C++](client-libraries-cpp.md) producer:
The following is an example of [C++](client-libraries-cpp.md) producer:

```cpp
Client client("pulsar://localhost:6650");
Expand All @@ -231,4 +230,4 @@ if (result != ResultOk) {
LOG_ERROR("Error creating producer: " << result);
return -1;
}
```
```

0 comments on commit f1f6b0c

Please sign in to comment.