+## Before You Begin
+
+Make sure you have already [installed the official CockroachDB Docker image](install-cockroachdb.html).
+
## 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.
PS C:\Users\username> 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
{{site.data.alerts.callout_info}}Be sure to replace
<username> in the
-v flag with your actual username.{{site.data.alerts.end}}
@@ -54,17 +58,21 @@ cockroachdb/cockroach:beta-20170209
start --insecure/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 `Users/
/cockroach-data/roach1` on the host and will persist after the container is stopped or deleted. For more details, see Docker's Mount a host directory as a data volume 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 --cache flag in the start 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:
{{site.data.alerts.callout_info}}Again, be sure to replace <username> in the -v flag with your actual username.{{site.data.alerts.end}}
@@ -89,42 +97,24 @@ 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 `Users//cockroach-data/roach2` and `Users//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:
PS C:\Users\username> docker exec -it roach1 ./cockroach sql
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.
PS C:\Users\username> docker exec -it roach2 ./cockroach sql
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.
+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:
+
+
+
+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 replication, rebalancing, fault tolerance 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):
@@ -181,6 +193,8 @@ Use the `docker stop` and `docker rm` commands to stop and remove the containers
[Secure your cluster](secure-a-cluster.html) with authentication and encryption. You might also be interested in:
-- [Manual Deployment](manual-deployment.html): How to run CockroachDB across multiple machines
-- [Cloud Deployment](cloud-deployment.html): How to run CockroachDB in the cloud
-- [Orchestration](orchestration.html): How to further automate CockroachDB with orchestration tools
+- [Explore Core Feature](demo-data-replication.html)
+- [Manual Deployment](manual-deployment.html)
+- [Cloud Deployment](cloud-deployment.html)
+- [Orchestration](orchestration.html)
+- [Import Data](import-data.html)
diff --git a/start-a-local-cluster.md b/start-a-local-cluster.md
index faef2538129..deda4b4bc90 100644
--- a/start-a-local-cluster.md
+++ b/start-a-local-cluster.md
@@ -6,19 +6,21 @@ toc_not_nested: true
asciicast: true
---
-Once you've [installed the CockroachDB binary](install-cockroachdb.html), it's simple to start a multi-node cluster locally with each node listening on a different port.
+Once you’ve [installed CockroachDB](install-cockroachdb.html), it’s simple to start a multi-node cluster locally with each node listening on a different port.
{{site.data.alerts.callout_info}}Running multiple nodes on a single host is useful for testing out CockroachDB, but it's not recommended for production deployments. To run a physically distributed cluster in production, see Manual Deployment, Cloud Deployment, or Orchestration.{{site.data.alerts.end}}
-## 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 CockroachDB](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.
-## Step 1. Start your first node
+
+
+## Step 1. Start the first node
~~~ shell
$ cockroach start --background
@@ -38,30 +40,28 @@ nodeID: 1
This command starts a node, accepting all [`cockroach start`](start-a-node.html) defaults.
-- Communication is insecure, with the server listening only on `localhost` on port `26257` for internal and client communication and on port `8080` for HTTP requests from the Admin UI.
- - To bind to different ports, set `--port=` and `--http-port=`.
- - To bind the Admin UI to a private IP address or host, set `--http-host=`.
- - To listen on an external hostname or IP address, set `--insecure` and `--host=`. For a demonstration, see [Manual Deployment](manual-deployment.html).
+- Communication is insecure, with the node listening on `localhost` on port `26257` for internal and client traffic and on port `8080` for HTTP requests from the Admin UI.
+- Node data is stored in the `cockroach-data` directory.
+- The `--background` flag runs the node in the background so you can continue the next steps in the same shell.
+- The [standard output](start-a-node.html#standard-output) gives you helpful details such as the CockroachDB version, the URL for the admin UI, and the SQL URL for clients.
-- Node data is stored in the `cockroach-data` directory. To store data in a different location, set `--store=`. To use multiple stores, set this flag separately for each.
+{{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 node per host. When you run multiple nodes on a single host, however, this default may lead to out-of-memory errors, especially if you test in a serious way. To avoid such errors, you can limit each node's cache size by setting the --cache flag in the start command.{{site.data.alerts.end}}
-- The `--background` flag runs the node in the background so you can continue the next steps in the same shell.
+## Step 2. Add nodes to the cluster
-- The [standard output](start-a-node.html#standard-output) gives you a helpful summary: the CockroachDB version; the URL for the admin UI; the SQL URL for your client code; the storage locations for node and debug log data; whether the node is the first in the cluster, joined an existing cluster for the first time, or rejoined an existing cluster; the cluster ID; and the node ID.
+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.
-{{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 node per host. When running multiple 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 --cache flag in the start command.{{site.data.alerts.end}}
+To simulate a real deployment, scale your cluster by adding two more nodes:
-## Step 2. Add nodes to the cluster
-
~~~ shell
-# Start your second node:
+# Start the second node:
$ cockroach start --background \
--store=node2 \
--port=26258 \
--http-port=8081 \
--join=localhost:26257
-# Start your third node:
+# Start the third node:
$ cockroach start --background \
--store=node3 \
--port=26259 \
@@ -69,21 +69,13 @@ $ cockroach start --background \
--join=localhost:26257
~~~
-These commands add two nodes to the cluster, but you can add as many as you like. For each node:
-
-- Set the `--store` flag to a storage location not in use by other nodes. To use multiple stores, set this flag separately for each.
-
-- Set the `--port` and `--http-port` flags to ports not in use by other nodes.
-
-- The `--join` flag connects the new node to the cluster. Set this flag to `localhost` and the port of the first node.
-
-- The `--background` flag runs the node in the background so you can continue the next steps in the same shell.
+The main difference here is that you use the `--join` flag to connect the new nodes to the cluster, specifying the address and port of the first node. Since you're running all nodes on the same machine, you also set the `--store`, `--port`, and `--http-port` flags to locations and ports not used by other nodes, but in a real deployment, with each node on a different machine, the defaults would suffice.
-{{site.data.alerts.callout_success}}If you don't plan to use more than one node, you can avoid unnecessary log messages about replication by editing the default replication zone to specify one node instead of three. See here for more details.{{site.data.alerts.end}}
+## Step 3. Test the cluster
-## Step 3. Use the built-in SQL client
+Now that you've scaled to 3 nodes, you can use any node as a SQL gateway to the cluster. To demonstrate this, start the [built-in SQL client](use-the-built-in-sql-client.html) on node 1:
-Start the [built-in SQL shell](use-the-built-in-sql-client.html) on node 1:
+{{site.data.alerts.callout_info}}The SQL client is built into the cockroach binary, so nothing extra is needed.{{site.data.alerts.end}}
~~~ shell
$ cockroach sql
@@ -92,32 +84,46 @@ $ 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);
+
+> INSERT INTO bank.accounts VALUES (1, 1000.50);
+
+> SELECT * FROM bank.accounts;
~~~
~~~
-CREATE TABLE
++----+---------+
+| id | balance |
++----+---------+
+| 1 | 1000.5 |
++----+---------+
+(1 row)
~~~
+Exit the SQL shell on node 1:
+
~~~ sql
-> INSERT INTO bank.accounts VALUES (1, 1000.50);
+> \q
~~~
-~~~
-INSERT 1
+Then start the SQL shell on node 2, this time specifying the node's non-default port:
+
+~~~ shell
+$ cockroach sql --port=26258
+# Welcome to the cockroach SQL interface.
+# All statements must be terminated by a semicolon.
+# To exit: CTRL + D.
~~~
+{{site.data.alerts.callout_info}}In a real deployment, all nodes would likely use the default port 26257, and so you wouldn't need to set the --port flag.{{site.data.alerts.end}}
+
+Now run the same `SELECT` query:
+
~~~ sql
> SELECT * FROM bank.accounts;
~~~
@@ -131,38 +137,86 @@ INSERT 1
(1 row)
~~~
-When you're done, use **CTRL + D**, **CTRL + C**, or `\q` to exit the SQL shell.
+As you can see, node 1 and node 2 behaved identically as SQL gateways.
-## Step 4. Open the Admin UI
+When you're done, exit the SQL shell on node 2:
+
+~~~ sql
+> \q
+~~~
-The CockroachDB [Admin UI](explore-the-admin-ui.html) lets you monitor cluster-wide, node-level, and database-level metrics and events. To start up the Admin UI, point your browser to `http://localhost:8080`. You can also find the address in the `admin` field in the standard output of any node on startup.
+## Step 4. Monitor the cluster
-{% include prometheus-callout.html %}
+To access the [Admin UI](explore-the-admin-ui.html) for your cluster, point a browser to `http://localhost:8080`, or to the address in the `admin` field in the standard output of any node on startup:
+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:
+
+
+
+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 replication, rebalancing, fault tolerance demos.{{site.data.alerts.end}}
+
## Step 5. Stop the cluster
-You can stop the nodes (and therefore the cluster) as follows:
+Once you're done with your test cluster, stop the first node:
~~~ shell
-# Stop node 1:
$ cockroach quit
+~~~
+
+With 2 nodes still online, the cluster remains operational because a majority of replicas are still available. You can verify that the cluster has tolerated this "failure" by starting the built-in SQL shell on nodes 2 or 3:
+
+~~~ shell
+$ cockroach sql --port=26258
+# Welcome to the cockroach SQL interface.
+# All statements must be terminated by a semicolon.
+# To exit: CTRL + D.
+~~~
+
+~~~ sql
+> SELECT * FROM bank.accounts;
+~~~
+
+~~~
++----+---------+
+| id | balance |
++----+---------+
+| 1 | 1000.5 |
++----+---------+
+(1 row)
+~~~
+
+Now stop the second node:
-# Stop node 2:
+~~~
$ cockroach quit --port=26258
+~~~
+
+With only 1 node online, a majority of replicas are no longer available, and so the cluster is not operational. As a result, you can't use `cockroach quit` to stop the last node, but instead must get the node's process ID and then force kill it:
-# Stop node 3:
-$ cockroach quit --port=26259
+~~~ shell
+# Get the process ID for node 3:
+$ ps | grep cockroach
~~~
-For more details about the `cockroach quit` command, see [Stop a Node](stop-a-node.html).
+~~~
+5084 ttys001 0:50.15 cockroach start --store=node3 --port=26259 --http-port=8082 --join=localhost:26257
+~~~
+
+~~~ shell
+# Force quit the process:
+$ kill -9 5084
+~~~
## What's Next?
[Secure your cluster](secure-a-cluster.html) with authentication and encryption. You might also be interested in:
-- [Manual Deployment](manual-deployment.html): How to run CockroachDB across multiple machines
-- [Cloud Deployment](cloud-deployment.html): How to run CockroachDB in the cloud
-- [Orchestration](orchestration.html): How to further automate CockroachDB with orchestration tools
-- [Import Data](import-data.html): How to import data from your application's current database
+- [Explore Core Feature](demo-data-replication.html)
+- [Manual Deployment](manual-deployment.html)
+- [Cloud Deployment](cloud-deployment.html)
+- [Orchestration](orchestration.html)
+- [Import Data](import-data.html)