Surface core value props in start a cluster

_includes/start_in_docker/mac-linux-steps.md

@@ -1,20 +1,22 @@
-## Watch a Demo
+## Before You Begin
 
-Feel free to watch this process in action before going through the steps yourself. Note that you can copy commands directly from the video, and you can use **<** and **>** to go back and forward.
+Make sure you have already [installed the official CockroachDB Docker image](install-cockroachdb.html).
+
+Also, feel free to watch this process in action before going through the steps yourself. Note that you can copy commands directly from the video, and you can use **<** and **>** to go back and forward.
 
 <asciinema-player class="asciinema-demo" src="asciicasts/start-a-local-cluster-docker.json" cols="107" speed="2" theme="monokai" poster="npt:0:43" title="Start a Local Cluster in Docker"></asciinema-player>
 
 ## Step 1. Create a bridge network
 
-Since you'll be running multiple Docker containers on a single host, with one CockroachDB node per container, you need to create what Docker refers to as a [bridge network](https://docs.docker.com/engine/userguide/networking/#/a-bridge-network). The bridge network will enable the containers to communicate as a single cluster while keeping them isolated from external networks. 
+Since you'll be running multiple Docker containers on a single host, with one CockroachDB node per container, you need to create what Docker refers to as a [bridge network](https://docs.docker.com/engine/userguide/networking/#/a-bridge-network). The bridge network will enable the containers to communicate as a single cluster while keeping them isolated from external networks.
 
 ~~~ shell
 $ docker network create -d bridge roachnet
 ~~~
 
 We've used `roachnet` as the network name here and in subsequent steps, but feel free to give your network any name you like.
 
-## Step 2. Start your first container/node
+## Step 2. Start the first node
 
 ~~~ shell
 $ docker run -d \
@@ -29,17 +31,21 @@ cockroachdb/cockroach:{{site.data.strings.version}} start --insecure
 This command creates a container and starts the first CockroachDB node inside it. Let's look at each part:
 
 - `docker run`: The Docker command to start a new container.
-- `-d`: This flag runs the container in the background so you can continue the next steps in the same shell. 
-- `--name`: The name for the container. This is optional, but a custom name makes it significantly easier to reference the container in other commands, for example, when opening a Bash session in the container or stopping the container. 
+- `-d`: This flag runs the container in the background so you can continue the next steps in the same shell.
+- `--name`: The name for the container. This is optional, but a custom name makes it significantly easier to reference the container in other commands, for example, when opening a Bash session in the container or stopping the container.
 - `--hostname`: The hostname for the container. You will use this to join other containers/nodes to the cluster.
 - `--net`: The bridge network for the container to join. See step 1 for more details.
 - `-p 26257:26257 -p 8080:8080`: These flags map the default port for inter-node and client-node communication (`26257`) and the default port for HTTP requests to the Admin UI (`8080`) from the container to the host. This enables inter-container communication and makes it possible to call up the Admin UI from a browser.
 - `-v "${PWD}/cockroach-data/roach1:/cockroach/cockroach-data"`: This flag mounts a host directory as a data volume. This means that data and logs for this node will be stored in `${PWD}/cockroach-data/roach1` on the host and will persist after the container is stopped or deleted. For more details, see Docker's <a href="https://docs.docker.com/engine/tutorials/dockervolumes/#/mount-a-host-directory-as-a-data-volume">Mount a host directory as a data volume</a> topic.
-- `cockroachdb/cockroach:{{site.data.strings.version}} start --insecure`: The CockroachDB command to [start a node](start-a-node.html) in the container in insecure mode. 
+- `cockroachdb/cockroach:{{site.data.strings.version}} start --insecure`: The CockroachDB command to [start a node](start-a-node.html) in the container in insecure mode.
 
   {{site.data.alerts.callout_success}}By default, each node's cache is limited to 25% of available memory. This default is reasonable when running one container/node per host. When running multiple containers/nodes on a single host, however, it may lead to out of memory errors, especially when testing against the cluster in a serious way. To avoid such errors, you can manually limit each node's cache size by setting the <a href="start-a-node.html#flags"><code>--cache</code></a> flag in the <code>start</code> command.{{site.data.alerts.end}}
 
-## Step 3. Start additional containers/nodes
+## Step 3. Add nodes to the cluster
+
+At this point, your cluster is live and operational. With just one node, you can already connect a SQL client and start building out your database. In real deployments, however, you'll always want 3 or more nodes to take advantage of CockroachDB's [automatic replication](demo-data-replication.html), [rebalancing](demo-automatic-rebalancing.html), and [fault tolerance](demo-fault-tolerance-and-recovery.html) capabilities.
+
+To simulate a real deployment, scale your cluster by adding two more nodes:
 
 ~~~ shell
 # Start the second container/node:
@@ -64,9 +70,9 @@ These commands add two more containers and start CockroachDB nodes inside them,
 - `-v`: This flag mounts a host directory as a data volume. Data and logs for these nodes will be stored in `${PWD}/cockroach-data/roach2` and `${PWD}/cockroach-data/roach3` on the host and will persist after the containers are stopped or deleted.
 - `--join`: This flag joins the new nodes to the cluster, using the first container's `hostname`. Otherwise, all [`cockroach start`](start-a-node.html) defaults are accepted. Note that since each node is in a unique container, using identical default ports won’t cause conflicts.
 
-## Step 4. Use the built-in SQL client
+## Step 4. Test the cluster
 
-Use the `docker exec` command to start the [built-in SQL shell](use-the-built-in-sql-client.html) in the first container:
+Now that you've scaled to 3 nodes, you can use any node as a SQL gateway to the cluster. To demonstrate this, use the `docker exec` command to start the [built-in SQL shell](use-the-built-in-sql-client.html) in the first container:
 
 ~~~ shell
 $ docker exec -it roach1 ./cockroach sql
@@ -75,33 +81,15 @@ $ docker exec -it roach1 ./cockroach sql
 # To exit: CTRL + D.
 ~~~
 
-Then run some [CockroachDB SQL statements](learn-cockroachdb-sql.html):
+Run some basic [CockroachDB SQL statements](learn-cockroachdb-sql.html):
 
 ~~~ sql
 > CREATE DATABASE bank;
-~~~
-
-~~~
-CREATE DATABASE
-~~~
 
-~~~ sql
 > CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);
-~~~
 
-~~~
-CREATE TABLE
-~~~
-
-~~~ sql
 > INSERT INTO bank.accounts VALUES (1, 1000.50);
-~~~
 
-~~~
-INSERT 1
-~~~
-
-~~~ sql
 > SELECT * FROM bank.accounts;
 ~~~
 
@@ -114,9 +102,13 @@ INSERT 1
 (1 row)
 ~~~
 
-When you're done, use **CTRL + D**, **CTRL + C**, or `\q` to exit the SQL shell.
+Exit the SQL shell on node 1:
+
+~~~ sql
+> \q
+~~~
 
-If you want to verify that the containers/nodes are, in fact, part of a single cluster, you can start the SQL shell in one of the other containers and check for the new `bank` database:
+Then start the SQL shell in the second container:
 
 ~~~ shell
 $ docker exec -it roach2 ./cockroach sql
@@ -125,25 +117,43 @@ $ docker exec -it roach2 ./cockroach sql
 # To exit: CTRL + D.
 ~~~
 
+Now run the same `SELECT` query:
+
 ~~~ sql
-> SHOW DATABASES;
+> SELECT * FROM bank.accounts;
 ~~~
 
 ~~~
-+----------+
-| Database |
-+----------+
-| bank     |
-| system   |
-+----------+
++----+---------+
+| id | balance |
++----+---------+
+|  1 |  1000.5 |
++----+---------+
+(1 row)
 ~~~
 
-## Step 5. Open the Admin UI
+As you can see, node 1 and node 2 behaved identically as SQL gateways.
+
+When you're done, exit the SQL shell on node 2:
+
+~~~ sql
+> \q
+~~~
+
+## Step 5. Monitor the cluster
 
 When you started the first container/node, you mapped the node's default HTTP port `8080` to port `8080` on the host. To check out the [Admin UI](explore-the-admin-ui.html) for your cluster, point your browser to that port on `localhost`, i.e., `http://localhost:8080`.
 
 <img src="images/admin_ui.png" alt="CockroachDB Admin UI" style="border:1px solid #eee;max-width:100%" />
 
+As mentioned earlier, CockroachDB automatically replicates your data behind-the-scenes. To verify that data written in the previous step was replicated successfully, scroll down to the **Replicas per Store** graph and hover over the line:
+
+<img src="images/admin_ui_replicas.png" alt="CockroachDB Admin UI" style="border:1px solid #eee;max-width:100%" />
+
+The replica count on each node is identical, indicating that all data in the cluster was replicated 3 times (the default).
+
+{{site.data.alerts.callout_success}}For more insight into how CockroachDB automatically replicates and rebalances data, and tolerates and recovers from failures, see our <a href="demo-data-replication.html">replication</a>, <a href="demo-automatic-rebalancing.html">rebalancing</a>, <a href="demo-fault-tolerance-and-recovery.html">fault tolerance</a> demos.{{site.data.alerts.end}}
+
 ## Step 6.  Stop the cluster
 
 Use the `docker stop` and `docker rm` commands to stop and remove the containers (and therefore the cluster):