Once you’ve installed the official CockroachDB Docker image, it’s simple to run a multi-node cluster across multiple Docker containers on a single host, using Docker volumes to persist node data.

Running a stateful application like CockroachDB in Docker is more complex and error-prone than most uses of Docker and is not recommended for production deployments. To run a physically distributed cluster in containers, use an orchestration tool like Kubernetes or Docker Swarm. See Orchestration for more details.

Before You Begin

Make sure you have already installed the official CockroachDB Docker image.

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. The bridge network will enable the containers to communicate as a single cluster while keeping them isolated from external networks.

$ 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 the first node

$ docker run -d \
--name=roach1 \
--hostname=roach1 \
--net=roachnet \
-p 26257:26257 -p 8080:8080  \
-v "${PWD}/cockroach-data/roach1:/cockroach/cockroach-data"  \
cockroachdb/cockroach:beta-20170420 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.
  • --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 Mount a host directory as a data volume topic.
  • cockroachdb/cockroach:beta-20170420 start --insecure: The CockroachDB command to start a node in the container in insecure mode.

    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.

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, rebalancing, and fault tolerance capabilities.

To simulate a real deployment, scale your cluster by adding two more nodes:

# Start the second container/node:
$ docker run -d \
--name=roach2 \
--hostname=roach2 \
--net=roachnet \
-v "${PWD}/cockroach-data/roach2:/cockroach/cockroach-data" \
cockroachdb/cockroach:beta-20170420 start --insecure --join=roach1

# Start the third container/node:
$ docker run -d \
--name=roach3 \
--hostname=roach3 \
--net=roachnet \
-v "${PWD}/cockroach-data/roach3:/cockroach/cockroach-data" \
cockroachdb/cockroach:beta-20170420 start --insecure --join=roach1

These commands add two more containers and start CockroachDB nodes inside them, joining them to the first node. There are only a few differences to note from step 2:

  • -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 defaults are accepted. Note that since each node is in a unique container, using identical default ports won’t cause conflicts.

Step 4. Test the cluster

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 in the first container:

$ docker exec -it roach1 ./cockroach sql --insecure
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.

Run some basic CockroachDB SQL statements:

> CREATE DATABASE bank;

> CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);

> INSERT INTO bank.accounts VALUES (1, 1000.50);

> SELECT * FROM bank.accounts;
+----+---------+
| id | balance |
+----+---------+
|  1 |  1000.5 |
+----+---------+
(1 row)

Exit the SQL shell on node 1:

> \q

Then start the SQL shell in the second container:

$ docker exec -it roach2 ./cockroach sql --insecure
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.

Now run the same SELECT query:

> SELECT * FROM bank.accounts;
+----+---------+
| id | balance |
+----+---------+
|  1 |  1000.5 |
+----+---------+
(1 row)

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:

> \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 for your cluster, point your browser to that port on localhost, i.e., http://localhost:8080.

CockroachDB Admin UI

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:

CockroachDB Admin UI

The replica count on each node is identical, indicating that all data in the cluster was replicated 3 times (the default).

For more insight into how CockroachDB automatically replicates and rebalances data, and tolerates and recovers from failures, see our replication, rebalancing, fault tolerance demos.

Step 6. Stop the cluster

Use the docker stop and docker rm commands to stop and remove the containers (and therefore the cluster):

# Stop the containers:
$ docker stop roach1 roach2 roach3

# Remove the containers:
$ docker rm roach1 roach2 roach3

Before You Begin

Make sure you have already installed the official CockroachDB Docker image.

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. The bridge network will enable the containers to communicate as a single cluster while keeping them isolated from external networks.

$ 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 the first node

$ docker run -d \
--name=roach1 \
--hostname=roach1 \
--net=roachnet \
-p 26257:26257 -p 8080:8080  \
-v "${PWD}/cockroach-data/roach1:/cockroach/cockroach-data"  \
cockroachdb/cockroach:beta-20170420 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.
  • --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 Mount a host directory as a data volume topic.
  • cockroachdb/cockroach:beta-20170420 start --insecure: The CockroachDB command to start a node in the container in insecure mode.

    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.

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, rebalancing, and fault tolerance capabilities.

To simulate a real deployment, scale your cluster by adding two more nodes:

# Start the second container/node:
$ docker run -d \
--name=roach2 \
--hostname=roach2 \
--net=roachnet \
-v "${PWD}/cockroach-data/roach2:/cockroach/cockroach-data" \
cockroachdb/cockroach:beta-20170420 start --insecure --join=roach1

# Start the third container/node:
$ docker run -d \
--name=roach3 \
--hostname=roach3 \
--net=roachnet \
-v "${PWD}/cockroach-data/roach3:/cockroach/cockroach-data" \
cockroachdb/cockroach:beta-20170420 start --insecure --join=roach1

These commands add two more containers and start CockroachDB nodes inside them, joining them to the first node. There are only a few differences to note from step 2:

  • -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 defaults are accepted. Note that since each node is in a unique container, using identical default ports won’t cause conflicts.

Step 4. Test the cluster

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 in the first container:

$ docker exec -it roach1 ./cockroach sql --insecure
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.

Run some basic CockroachDB SQL statements:

> CREATE DATABASE bank;

> CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);

> INSERT INTO bank.accounts VALUES (1, 1000.50);

> SELECT * FROM bank.accounts;
+----+---------+
| id | balance |
+----+---------+
|  1 |  1000.5 |
+----+---------+
(1 row)

Exit the SQL shell on node 1:

> \q

Then start the SQL shell in the second container:

$ docker exec -it roach2 ./cockroach sql --insecure
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.

Now run the same SELECT query:

> SELECT * FROM bank.accounts;
+----+---------+
| id | balance |
+----+---------+
|  1 |  1000.5 |
+----+---------+
(1 row)

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:

> \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 for your cluster, point your browser to that port on localhost, i.e., http://localhost:8080.

CockroachDB Admin UI

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:

CockroachDB Admin UI

The replica count on each node is identical, indicating that all data in the cluster was replicated 3 times (the default).

For more insight into how CockroachDB automatically replicates and rebalances data, and tolerates and recovers from failures, see our replication, rebalancing, fault tolerance demos.

Step 6. Stop the cluster

Use the docker stop and docker rm commands to stop and remove the containers (and therefore the cluster):

# Stop the containers:
$ docker stop roach1 roach2 roach3

# Remove the containers:
$ docker rm roach1 roach2 roach3

Before You Begin

Make sure you have already installed the official CockroachDB Docker image.

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. 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 the first node

Be sure to replace <username> in the -v flag with your actual username.
PS C:\Users\username> docker run -d `
--name=roach1 `
--hostname=roach1 `
--net=roachnet `
-p 26257:26257 -p 8080:8080 `
-v "//c/Users/<username>/cockroach-data/roach1:/cockroach/cockroach-data" `
cockroachdb/cockroach:beta-20170209 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.
  • --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 "//c/Users/<username>/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/<username>/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:beta-20170420 start --insecure: The CockroachDB command to start a node in the container in insecure mode.

    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.

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, rebalancing, and fault tolerance capabilities.

To simulate a real deployment, scale your cluster by adding two more nodes:

Again, be sure to replace <username> in the -v flag with your actual username.
# Start the second container/node:
PS C:\Users\username> docker run -d `
--name=roach2 `
--hostname=roach2 `
--net=roachnet `
-v "//c/Users/<username>/cockroach-data/roach2:/cockroach/cockroach-data" `
cockroachdb/cockroach:beta-20170209 start --insecure --join=roach1

# Start the third container/node:
PS C:\Users\username> docker run -d `
--name=roach3 `
--hostname=roach3 `
--net=roachnet `
-v "//c/Users/<username>/cockroach-data/roach3:/cockroach/cockroach-data" `
cockroachdb/cockroach:beta-20170209 start --insecure --join=roach1

These commands add two more containers and start CockroachDB nodes inside them, joining them to the first node. There are only a few differences to note from step 2:

  • -v: This flag mounts a host directory as a data volume. Data and logs for these nodes will be stored in Users/<username>/cockroach-data/roach2 and Users/<username>/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 defaults are accepted. Note that since each node is in a unique container, using identical default ports won’t cause conflicts.

Step 4. Test the cluster

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 in the first container:

PS C:\Users\username> docker exec -it roach1 ./cockroach sql --insecure
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.

Run some basic CockroachDB SQL statements:

> CREATE DATABASE bank;

> CREATE TABLE bank.accounts (id INT PRIMARY KEY, balance DECIMAL);

> INSERT INTO bank.accounts VALUES (1, 1000.50);

> SELECT * FROM bank.accounts;
+----+---------+
| id | balance |
+----+---------+
|  1 |  1000.5 |
+----+---------+
(1 row)

Exit the SQL shell on node 1:

> \q

Then start the SQL shell in the second container:

PS C:\Users\username> docker exec -it roach2 ./cockroach sql --insecure
# Welcome to the cockroach SQL interface.
# All statements must be terminated by a semicolon.
# To exit: CTRL + D.

Now run the same SELECT query:

> SELECT * FROM bank.accounts;
+----+---------+
| id | balance |
+----+---------+
|  1 |  1000.5 |
+----+---------+
(1 row)

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:

> \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 for your cluster, point your browser to that port on localhost, i.e., http://localhost:8080.

CockroachDB Admin UI

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:

CockroachDB Admin UI

The replica count on each node is identical, indicating that all data in the cluster was replicated 3 times (the default).

For more insight into how CockroachDB automatically replicates and rebalances data, and tolerates and recovers from failures, see our replication, rebalancing, fault tolerance demos.

Step 6. Stop the cluster

Use the docker stop and docker rm commands to stop and remove the containers (and therefore the cluster):

# Stop the containers:
PS C:\Users\username> docker stop roach1 roach2 roach3

# Remove the containers:
PS C:\Users\username> docker rm roach1 roach2 roach3

What’s Next?

Secure your cluster with authentication and encryption. You might also be interested in:



Yes No