How to Create a CockroachDB in Docker


If you’re developing and deploying applications using Docker, you may find that you need to set up CockroachDB to run in a Docker container. Fortunately, this task isn’t a difficult one to accomplish. In this article, we’ll provide step-by-step instructions for setting up and starting CockroachDB in a Docker container.


Before we start working on the CockroachDB setup process in Docker, we need to go over a few key prerequisites that need to be in place:

  • First, make sure that there is a Cockroach database installed on your machine. To find out if it’s already installed, use the command cockroach version in the terminal.

  • You’ll also need to confirm that there’s a Docker container installed and verify its status. If you’re running a Linux distribution that uses the systemd software suite, use the command sudo systemctl status docker in a terminal window to make sure that Docker is working properly. You can just use the command docker info in a Windows command prompt or in any UNIX-based terminal to have Docker return more information.

  • Be sure to pull the latest cockroachdb/cockroach image from the official CockroachDB Docker image store in Docker Hub. You can do so using the following command:

docker pull cockroachdb/cockroach

Local cluster in Docker

Now that we’ve covered the necessary prerequisites, we can start creating the CockroachDB cluster in our Docker container.

Make a network bridge

We’ll be creating a CockroachDB node with the same host that will be running on multiple containers in Docker. This will allow the containers to communicate while the network is being hidden from outside networks.

We can use the following command to create a network bridge:

docker network create -d bridge [network_name]

Run the local cluster

Next, we’ll need to pull the Cockroach image in a Docker container when it’s not installed. This is an easy way to get CockroachDB set up on your local device. We’ll use Docker to create and start the local cluster in CockroachDB and create a new node.

The following command will pull and run CockroachDB in a Docker container and then bind-mount the data volume to the current working directory ($PWD):

docker run -d --name=rocket1 \
--hostname=rocket1 --net=objectrocket \
-p 26257:26257 -p 8080:8080 \
-v "${PWD}/cockroach-data/rocket1:/cockroach/cockroach-data" \
cockroach/cockroach:v19.2.0 start \
-- insecure --join=rocket1,rocket2,rocket3

NOTE: Keep in mind that we’ll be using different containers, so we won’t have issues with port restrictions in CockroachDB cluster even if the ports are the same.

Before we move forward, let’s take a closer look at the flags used in this command to fully understand what’s going on:

  • We use the docker run command to start a container.

  • We use the -d flag in the command-line interface while running a Docker container in the background.

  • We can then set the name of the Docker container by using the --name flag.

  • The --hostname flag is used to connect and join the other nodes in the cluster.

  • The --net flag is used to allow the nodes or the container to join in the bridge network.

  • The -p flag indicates the port number. The default local port for a CockroachDB node is 26257:26257, and 8080:8080 is the default port for the Admin UI for HTTP browser requests.

  • We can use the -v flag to store the logs of the node; using this flag will persist data if the container is deleted or stopped.

  • The cockroachdb/cockroach:v19.2.0 start command is used to start a node in the CockroachDB cluster and in the Docker container.

  • We can set the flag --insecure to use the cluster locally without using an authentication certificate and key. However, it’s important to know that this mode is not confidential and has no security functions.

  • The --join flag identifies the hostnames of all the nodes that will be part of your cluster.

Create multiple nodes

If you want to create multiple nodes, you can use the same command that was shown in the previous instructions; however, you’ll need to change the name and hostname and remove the port.

Let’s check out an example:

docker run -d --name=rocket2 \
--hostname=rocket2 --net=objectrocket \
-v "${PWD}/cockroach-data/rocket2:/cockroach/cockroach-data" \
cockroach/cockroach:v19.2.0 start \
-- insecure --join=rocket1,rocket2,rocket3

Here’s another example:

docker run -d --name=rocket3 \
--hostname=rocket3 --net=objectrocket \
-v "${PWD}/cockroach-data/rocket3:/cockroach/cockroach-data" \
cockroach/cockroach:v19.2.0 start \
-- insecure --join=rocket1,rocket2,rocket3

Start the initialization of the cluster

docker exec -it rocket1 ./cockroach init --insecure
Cluster successfully initialized

Now that we’ve started the cluster, we can use the SQL shell to execute SQL commands and create an example. We’ll use the port localhost:8080 to view the graphical user interface in the browser.

Our first step will be to open the SQL shell command line console on the first node.

docker exec -it rocket1 ./cockroach sql --insecure

Then we’ll create a Cockroach database and table. To create a database in CockroachDB, we’ll use this SQL command:

CREATE DATABASE objectrocket;

To connect to a specific database, we use the command USE [database_name].

We’ll then proceed to create our table, using the SQL statement shown below:


After we create the table, we can insert a record into it:

INSERT INTO demo VALUES(1, 'objectrockets', TRUE);

Using the SELECT statement, we can display the record we inserted into the table demo:

root@:26257/objectrocket> SELECT * FROM demo;
id | string | bool
1 | objectrockets | TRUE
(1 ROW)

TIME: 16.297744ms

At this point, we can try to open a new terminal for the other node example that’s been created earlier. We can also open the sql command-line console for both nodes:

docker exec -it rocket2 ./cockroach sql --insecure

NOTE: To display the replicated data inserted in the rocket1 table, simply connect to the database ‘objectrocket‘ and use a SELECT statement.


When you’re developing applications that interact with CockroachDB, it can be helpful to build and deploy your applications in a Docker container. Fortunately, it’s easy to set up and start a CockroachDB cluster within Docker. In this article, we showed you how to get started with Docker and CockroachDB. Using these instructions and examples, you’ll be able to implement CockroachDB in a Docker container for your own development efforts.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.