Merge pull request #297 from confluentinc/0.1.x-bootstrap-servers

Document how to configure the Kafka bootstrap servers

docs/concepts.md

@@ -38,7 +38,7 @@ A table is a view of a stream, or another table, and represents a collection of
 ## Standalone mode
 
 In stand-alone mode, both the KSQL client and server components are co-located on the same machine, in the same JVM,
-and are started together.  This make standalone mode very convenient for local development and testing.
+and are started together.  This makes standalone mode very convenient for local development and testing.
 
 ![Standalone mode](/docs/img/standalone-mode.png)
 
@@ -51,10 +51,13 @@ To run KSQL in standalone mode:
         $ ./bin/ksql-cli local
         ```
 
-    -  Start with custom settings:
+    -  Start with [custom settings](/docs/syntax-reference.md#configuring-ksql), pointing KSQL at a specific
+       Kafka cluster (see Kafka's [bootstrap.servers](https://kafka.apache.org/documentation/#newconsumerconfigs)
+       setting):
 
         ```bash
-        $ ./bin/ksql-cli local --properties-file path/to/ksql-cli.properties
+        $ ./bin/ksql-cli local --bootstrap-server kafka-broker-1:9092 \
+                               --properties-file path/to/ksql-cli.properties
         ```
 
 
@@ -74,12 +77,32 @@ To run KSQL in client-server mode:
         $ ./bin/ksql-server-start
         ```
 
-    -  Start with custom settings:
+    -  Start with [custom settings](/docs/syntax-reference.md#configuring-ksql), pointing KSQL at a specific
+       Kafka cluster (see Kafka's [bootstrap.servers](https://kafka.apache.org/documentation/#newconsumerconfigs)
+       setting):
 
         ```bash
-        $ ./bin/ksql-server-start --properties-file ksql-server.properties
+        $ hostname
+        my-ksql-server
+
+        $ cat ksql-server.properties
+        # You must set at least the following two properties
+        bootstrap.servers=kafka-broker-1:9092
+        # Note: `application.id` is not really needed but you must set it
+        #       because of a known issue in the KSQL Developer Preview
+        application.id=app-id-setting-is-ignored
+
+        # Optional settings below, only for illustration purposes
+        # The hostname/port on which the server node will listen for client connections
+        listeners=http://0.0.0.0:8090
         ```
-- Start any number of CLIs, specifying a KSQL server address as the `remote` endpoint:
+
+        To start the server node with the settings above:
+
+        ```bash
+        $ ./bin/ksql-server-start ksql-server.properties
+        ```
+- Start any number of CLIs, specifying the desired KSQL server address as the `remote` endpoint:
 
   ```bash
   $ ./bin/ksql-cli remote http://my-ksql-server:8090

docs/syntax-reference.md

@@ -514,6 +514,8 @@ ksql> SET 'commit.interval.ms'='5000';
 
 Both property name and property value should be enclosed in single quotes.
 
+> Tip: `SHOW PROPERTIES` shows the current settings.
+
 Once a property has been set, it will remain in effect for the remainder of the KSQL CLI session until you issue another
 SET statement to change it.